<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Module: ActionController::Resources</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" />
<script type="text/javascript">
// <![CDATA[
function popupCode( url ) {
window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
}
function toggleCode( id ) {
if ( document.getElementById )
elem = document.getElementById( id );
else if ( document.all )
elem = eval( "document.all." + id );
else
return false;
elemStyle = elem.style;
if ( elemStyle.display != "block" ) {
elemStyle.display = "block"
} else {
elemStyle.display = "none"
}
return true;
}
// Make codeblocks hidden by default
document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
// ]]>
</script>
</head>
<body>
<div id="classHeader">
<table class="header-table">
<tr class="top-aligned-row">
<td><strong>Module</strong></td>
<td class="class-name-in-header">ActionController::Resources</td>
</tr>
<tr class="top-aligned-row">
<td><strong>In:</strong></td>
<td>
<a href="../../files/lib/action_controller/resources_rb.html">
lib/action_controller/resources.rb
</a>
<br />
</td>
</tr>
</table>
</div>
<!-- banner header -->
<div id="bodyContent">
<div id="contextContent">
<div id="description">
<h2>Overview</h2>
<p>
<a href="Resources.html">ActionController::Resources</a> are a way of
defining RESTful \<a href="Resources.html#M000160">resources</a>. A RESTful
\<a href="Resources.html#M000161">resource</a>, in basic terms, is
something that can be pointed at and it will respond with a representation
of the data requested. In real terms this could mean a user with a browser
requests an HTML page, or that a desktop application requests XML data.
</p>
<p>
RESTful design is based on the assumption that there are four generic verbs
that a user of an application can request from a \<a
href="Resources.html#M000161">resource</a> (the noun).
</p>
<p>
\<a href="Resources.html">Resources</a> can be requested using four basic
HTTP verbs (GET, POST, PUT, DELETE), the method used denotes the type of
action that should take place.
</p>
<h3>The Different Methods and their Usage</h3>
<ul>
<li>GET - Requests for a \<a href="Resources.html#M000161">resource</a>, no
saving or editing of a \<a href="Resources.html#M000161">resource</a>
should occur in a GET request.
</li>
<li>POST - Creation of \<a href="Resources.html#M000160">resources</a>.
</li>
<li>PUT - Editing of attributes on a \<a
href="Resources.html#M000161">resource</a>.
</li>
<li>DELETE - Deletion of a \<a href="Resources.html#M000161">resource</a>.
</li>
</ul>
<h3>Examples</h3>
<pre>
# A GET request on the Posts resource is asking for all Posts
GET /posts
# A GET request on a single Post resource is asking for that particular Post
GET /posts/1
# A POST request on the Posts resource is asking for a Post to be created with the supplied details
POST /posts # with => { :post => { :title => "My Whizzy New Post", :body => "I've got a brand new combine harvester" } }
# A PUT request on a single Post resource is asking for a Post to be updated
PUT /posts # with => { :id => 1, :post => { :title => "Changed Whizzy Title" } }
# A DELETE request on a single Post resource is asking for it to be deleted
DELETE /posts # with => { :id => 1 }
</pre>
<p>
By using the REST convention, users of our application can assume certain
things about how the data is requested and how it is returned. Rails
simplifies the routing part of RESTful design by supplying you with methods
to create them in your routes.rb file.
</p>
<p>
Read more about REST at <a
href="http://en.wikipedia.org/wiki/Representational_State_Transfer">en.wikipedia.org/wiki/Representational_State_Transfer</a>
</p>
</div>
</div>
<div id="method-list">
<h3 class="section-bar">Methods</h3>
<div class="name-list">
<a href="#M000161">resource</a>
<a href="#M000160">resources</a>
</div>
</div>
</div>
<!-- if includes -->
<div id="section">
<div id="constants-list">
<h3 class="section-bar">Constants</h3>
<div class="name-list">
<table summary="Constants">
<tr class="top-aligned-row context-row">
<td class="context-item-name">INHERITABLE_OPTIONS</td>
<td>=</td>
<td class="context-item-value">:namespace, :shallow</td>
</tr>
</table>
</div>
</div>
<!-- if method_list -->
<div id="methods">
<h3 class="section-bar">Public Instance methods</h3>
<div id="method-M000161" class="method-detail">
<a name="M000161"></a>
<div class="method-heading">
<a href="Resources.src/M000161.html" target="Code" class="method-signature"
onclick="popupCode('Resources.src/M000161.html');return false;">
<span class="method-name">resource</span><span class="method-args">(*entities, &block)</span>
</a>
</div>
<div class="method-description">
<p>
Creates named routes for implementing verb-oriented controllers for a
singleton \<a href="Resources.html#M000161">resource</a>. A singleton \<a
href="Resources.html#M000161">resource</a> is global to its current
context. For unnested singleton \<a
href="Resources.html#M000160">resources</a>, the \<a
href="Resources.html#M000161">resource</a> is global to the current user
visiting the application, such as a user‘s <tt>/account</tt> profile.
For nested singleton \<a href="Resources.html#M000160">resources</a>, the
\<a href="Resources.html#M000161">resource</a> is global to its parent \<a
href="Resources.html#M000161">resource</a>, such as a <tt>projects</tt> \<a
href="Resources.html#M000161">resource</a> that <tt>has_one
:project_manager</tt>. The <tt>project_manager</tt> should be mapped as a
singleton \<a href="Resources.html#M000161">resource</a> under
<tt>projects</tt>:
</p>
<pre>
map.resources :projects do |project|
project.resource :project_manager
end
</pre>
<p>
See <tt><a href="Resources.html#M000160">resources</a></tt> for general
conventions. These are the main differences:
</p>
<ul>
<li>A singular name is given to <tt>map.resource</tt>. The default controller
name is still taken from the plural name.
</li>
<li>To specify a custom plural name, use the <tt>:plural</tt> option. There is
no <tt>:singular</tt> option.
</li>
<li>No default index route is created for the singleton \<a
href="Resources.html#M000161">resource</a> controller.
</li>
<li>When nesting singleton \<a href="Resources.html#M000160">resources</a>,
only the singular name is used as the path prefix (example:
‘account/messages/1’)
</li>
</ul>
<p>
For example:
</p>
<pre>
map.resource :account
</pre>
<p>
maps these actions in the Accounts controller:
</p>
<pre>
class AccountsController < ActionController::Base
# GET new_account_url
def new
# return an HTML form for describing the new account
end
# POST account_url
def create
# create an account
end
# GET account_url
def show
# find and return the account
end
# GET edit_account_url
def edit
# return an HTML form for editing the account
end
# PUT account_url
def update
# find and update the account
end
# DELETE account_url
def destroy
# delete the account
end
end
</pre>
<p>
Along with the routes themselves, <tt><a
href="Resources.html#M000161">resource</a></tt> generates named routes for
use in controllers and views. <tt>map.resource :account</tt> produces these
named routes and helpers:
</p>
<pre>
Named Route Helpers
============ =============================================
account account_url, hash_for_account_url,
account_path, hash_for_account_path
new_account new_account_url, hash_for_new_account_url,
new_account_path, hash_for_new_account_path
edit_account edit_account_url, hash_for_edit_account_url,
edit_account_path, hash_for_edit_account_path
</pre>
</div>
</div>
<div id="method-M000160" class="method-detail">
<a name="M000160"></a>
<div class="method-heading">
<a href="Resources.src/M000160.html" target="Code" class="method-signature"
onclick="popupCode('Resources.src/M000160.html');return false;">
<span class="method-name">resources</span><span class="method-args">(*entities, &block)</span>
</a>
</div>
<div class="method-description">
<p>
Creates named routes for implementing verb-oriented controllers for a
collection \<a href="Resources.html#M000161">resource</a>.
</p>
<p>
For example:
</p>
<pre>
map.resources :messages
</pre>
<p>
will map the following actions in the corresponding controller:
</p>
<pre>
class MessagesController < ActionController::Base
# GET messages_url
def index
# return all messages
end
# GET new_message_url
def new
# return an HTML form for describing a new message
end
# POST messages_url
def create
# create a new message
end
# GET message_url(:id => 1)
def show
# find and return a specific message
end
# GET edit_message_url(:id => 1)
def edit
# return an HTML form for editing a specific message
end
# PUT message_url(:id => 1)
def update
# find and update a specific message
end
# DELETE message_url(:id => 1)
def destroy
# delete a specific message
end
end
</pre>
<p>
Along with the routes themselves, <tt><a
href="Resources.html#M000160">resources</a></tt> generates named routes for
use in controllers and views. <tt>map.resources :messages</tt> produces the
following named routes and helpers:
</p>
<pre>
Named Route Helpers
============ =====================================================
messages messages_url, hash_for_messages_url,
messages_path, hash_for_messages_path
message message_url(id), hash_for_message_url(id),
message_path(id), hash_for_message_path(id)
new_message new_message_url, hash_for_new_message_url,
new_message_path, hash_for_new_message_path
edit_message edit_message_url(id), hash_for_edit_message_url(id),
edit_message_path(id), hash_for_edit_message_path(id)
</pre>
<p>
You can use these helpers instead of <tt>url_for</tt> or methods that take
<tt>url_for</tt> parameters. For example:
</p>
<pre>
redirect_to :controller => 'messages', :action => 'index'
# and
<%= link_to "edit this message", :controller => 'messages', :action => 'edit', :id => @message.id %>
</pre>
<p>
now become:
</p>
<pre>
redirect_to messages_url
# and
<%= link_to "edit this message", edit_message_url(@message) # calls @message.id automatically
</pre>
<p>
Since web browsers don‘t support the PUT and DELETE verbs, you will
need to add a parameter ‘_method’ to your form tags. The form
helpers make this a little easier. For an update form with a
<tt>@message</tt> object:
</p>
<pre>
<%= form_tag message_path(@message), :method => :put %>
</pre>
<p>
or
</p>
<pre>
<% form_for :message, @message, :url => message_path(@message), :html => {:method => :put} do |f| %>
</pre>
<p>
or
</p>
<pre>
<% form_for @message do |f| %>
</pre>
<p>
which takes into account whether <tt>@message</tt> is a new record or not
and generates the path and method accordingly.
</p>
<p>
The <tt><a href="Resources.html#M000160">resources</a></tt> method accepts
the following options to customize the resulting routes:
</p>
<ul>
<li><tt>:collection</tt> - Add named routes for other actions that operate on
the collection. Takes a hash of <tt>#{action} => #{method}</tt>, where
method is <tt>:get</tt>/<tt>:post</tt>/<tt>:put</tt>/<tt>:delete</tt>, an
array of any of the previous, or <tt>:any</tt> if the method does not
matter. These routes map to a URL like /messages/rss, with a route of
<tt>rss_messages_url</tt>.
</li>
<li><tt>:member</tt> - Same as <tt>:collection</tt>, but for actions that
operate on a specific member.
</li>
<li><tt>:new</tt> - Same as <tt>:collection</tt>, but for actions that operate
on the new \<a href="Resources.html#M000161">resource</a> action.
</li>
<li><tt>:controller</tt> - Specify the controller name for the routes.
</li>
<li><tt>:singular</tt> - Specify the singular name used in the member routes.
</li>
<li><tt>:requirements</tt> - Set custom routing parameter requirements; this is
a hash of either
<pre>
regular expressions (which must match for the route to match) or extra parameters. For example:
map.resource :profile, :path_prefix => ':name', :requirements => { :name => /[a-zA-Z]+/, :extra => 'value' }
will only match if the first part is alphabetic, and will pass the parameter :extra to the controller.
</pre>
</li>
<li><tt>:conditions</tt> - Specify custom routing recognition conditions. \<a
href="Resources.html">Resources</a> sets the <tt>:method</tt> value for the
method-specific routes.
</li>
<li><tt>:as</tt> - Specify a different \<a
href="Resources.html#M000161">resource</a> name to use in the URL path. For
example:
<pre>
# products_path == '/productos'
map.resources :products, :as => 'productos' do |product|
# product_reviews_path(product) == '/productos/1234/comentarios'
product.resources :product_reviews, :as => 'comentarios'
end
</pre>
</li>
<li><tt>:has_one</tt> - Specify nested \<a
href="Resources.html#M000160">resources</a>, this is a shorthand for
mapping singleton \<a href="Resources.html#M000160">resources</a> beneath
the current.
</li>
<li><tt>:has_many</tt> - Same has <tt>:has_one</tt>, but for plural \<a
href="Resources.html#M000160">resources</a>.
<p>
You may directly specify the routing association with <tt>has_one</tt> and
<tt>has_many</tt> like:
</p>
<pre>
map.resources :notes, :has_one => :author, :has_many => [:comments, :attachments]
</pre>
<p>
This is the same as:
</p>
<pre>
map.resources :notes do |notes|
notes.resource :author
notes.resources :comments
notes.resources :attachments
end
</pre>
</li>
<li><tt>:path_names</tt> - Specify different path names for the actions. For
example:
<pre>
# new_products_path == '/productos/nuevo'
# bids_product_path(1) == '/productos/1/licitacoes'
map.resources :products, :as => 'productos', :member => { :bids => :get }, :path_names => { :new => 'nuevo', :bids => 'licitacoes' }
</pre>
<p>
You can also set default action names from an environment, like this:
</p>
<pre>
config.action_controller.resources_path_names = { :new => 'nuevo', :edit => 'editar' }
</pre>
</li>
<li><tt>:path_prefix</tt> - Set a prefix to the routes with required route
variables.
<p>
Weblog comments usually belong to a post, so you might use <tt><a
href="Resources.html#M000160">resources</a></tt> like:
</p>
<pre>
map.resources :articles
map.resources :comments, :path_prefix => '/articles/:article_id'
</pre>
<p>
You can nest <tt><a href="Resources.html#M000160">resources</a></tt> calls
to set this automatically:
</p>
<pre>
map.resources :articles do |article|
article.resources :comments
end
</pre>
<p>
The comment \<a href="Resources.html#M000160">resources</a> work the same,
but must now include a value for <tt>:article_id</tt>.
</p>
<pre>
article_comments_url(@article)
article_comment_url(@article, @comment)
article_comments_url(:article_id => @article)
article_comment_url(:article_id => @article, :id => @comment)
</pre>
<p>
If you don‘t want to load all objects from the database you might
want to use the <tt>article_id</tt> directly:
</p>
<pre>
articles_comments_url(@comment.article_id, @comment)
</pre>
</li>
<li><tt>:name_prefix</tt> - Define a prefix for all generated routes, usually
ending in an underscore. Use this if you have named routes that may clash.
<pre>
map.resources :tags, :path_prefix => '/books/:book_id', :name_prefix => 'book_'
map.resources :tags, :path_prefix => '/toys/:toy_id', :name_prefix => 'toy_'
</pre>
</li>
</ul>
<p>
You may also use <tt>:name_prefix</tt> to override the generic named routes
in a nested \<a href="Resources.html#M000161">resource</a>:
</p>
<pre>
map.resources :articles do |article|
article.resources :comments, :name_prefix => nil
end
</pre>
<p>
This will yield named \<a href="Resources.html#M000160">resources</a> like
so:
</p>
<pre>
comments_url(@article)
comment_url(@article, @comment)
</pre>
<ul>
<li><tt>:shallow</tt> - If true, paths for nested <a
href="Resources.html#M000160">resources</a> which reference a specific
member (ie. those with an :id parameter) will not use the parent path
prefix or name prefix.
</li>
</ul>
<p>
The <tt>:shallow</tt> option is inherited by any nested <a
href="Resources.html#M000161">resource</a>(s).
</p>
<p>
For example, ‘users’, ‘posts’ and
‘comments’ all use shallow paths with the following nested <a
href="Resources.html#M000160">resources</a>:
</p>
<pre>
map.resources :users, :shallow => true do |user|
user.resources :posts do |post|
post.resources :comments
end
end
# --> GET /users/1/posts (maps to the PostsController#index action as usual)
# also adds the usual named route called "user_posts"
# --> GET /posts/2 (maps to the PostsController#show action as if it were not nested)
# also adds the named route called "post"
# --> GET /posts/2/comments (maps to the CommentsController#index action)
# also adds the named route called "post_comments"
# --> GET /comments/2 (maps to the CommentsController#show action as if it were not nested)
# also adds the named route called "comment"
</pre>
<p>
You may also use <tt>:shallow</tt> in combination with the <tt>has_one</tt>
and <tt>has_many</tt> shorthand notations like:
</p>
<pre>
map.resources :users, :has_many => { :posts => :comments }, :shallow => true
</pre>
<ul>
<li><tt>:only</tt> and <tt>:except</tt> - Specify which of the seven default
actions should be routed to.
</li>
</ul>
<p>
<tt>:only</tt> and <tt>:except</tt> may be set to <tt>:all</tt>,
<tt>:none</tt>, an action name or a list of action names. By default,
routes are generated for all seven actions.
</p>
<p>
For example:
</p>
<pre>
map.resources :posts, :only => [:index, :show] do |post|
post.resources :comments, :except => [:update, :destroy]
end
# --> GET /posts (maps to the PostsController#index action)
# --> POST /posts (fails)
# --> GET /posts/1 (maps to the PostsController#show action)
# --> DELETE /posts/1 (fails)
# --> POST /posts/1/comments (maps to the CommentsController#create action)
# --> PUT /posts/1/comments/1 (fails)
</pre>
<p>
If <tt>map.resources</tt> is called with multiple <a
href="Resources.html#M000160">resources</a>, they all get the same options
applied.
</p>
<p>
Examples:
</p>
<pre>
map.resources :messages, :path_prefix => "/thread/:thread_id"
# --> GET /thread/7/messages/1
map.resources :messages, :collection => { :rss => :get }
# --> GET /messages/rss (maps to the #rss action)
# also adds a named route called "rss_messages"
map.resources :messages, :member => { :mark => :post }
# --> POST /messages/1/mark (maps to the #mark action)
# also adds a named route called "mark_message"
map.resources :messages, :new => { :preview => :post }
# --> POST /messages/new/preview (maps to the #preview action)
# also adds a named route called "preview_new_message"
map.resources :messages, :new => { :new => :any, :preview => :post }
# --> POST /messages/new/preview (maps to the #preview action)
# also adds a named route called "preview_new_message"
# --> /messages/new can be invoked via any request method
map.resources :messages, :controller => "categories",
:path_prefix => "/category/:category_id",
:name_prefix => "category_"
# --> GET /categories/7/messages/1
# has named route "category_message"
</pre>
<p>
The <tt><a href="Resources.html#M000160">resources</a></tt> method sets
HTTP method restrictions on the routes it generates. For example, making an
HTTP POST on <tt>new_message_url</tt> will raise a RoutingError exception.
The default route in <tt>config/routes.rb</tt> overrides this and allows
invalid HTTP methods for \<a href="Resources.html#M000161">resource</a>
routes.
</p>
</div>
</div>
</div>
</div>
<div id="validator-badges">
<p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
8b99df826c3b6cf56a1caaae5f931d50
>
files
>
527
