| Module | ActionController::Resources |
| In: |
lib/action_controller/resources.rb
|
ActionController::Resources are a way of defining RESTful resources. A RESTful resource, 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.
RESTful design is based on the assumption that there are four generic verbs that a user of an application can request from a resource (the noun).
Resources can be requested using four basic HTTP verbs (GET, POST, PUT, DELETE), the method used denotes the type of action that should take place.
GET Requests for a resource, no saving or editing of a resource should occur in a GET request POST Creation of resources PUT Editing of attributes on a resource DELETE Deletion of a resource
# 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 }
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.
Read more about REST at en.wikipedia.org/wiki/Representational_State_Transfer
Creates named routes for implementing verb-oriented controllers for a singleton resource. A singleton resource is global to its current context. For unnested singleton resources, the resource is global to the current user visiting the application, such as a user‘s /account profile. For nested singleton resources, the resource is global to its parent resource, such as a projects resource that has_one :project_manager. The project_manager should be mapped as a singleton resource under projects:
map.resources :projects do |project|
project.resource :project_manager
end
See map.resources for general conventions. These are the main differences:
For example:
map.resource :account
maps these actions in the Accounts controller:
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
Along with the routes themselves, resource generates named routes for use in controllers and views. map.resource :account produces these named routes and helpers:
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
Creates named routes for implementing verb-oriented controllers for a collection resource.
For example:
map.resources :messages
will map the following actions in the corresponding controller:
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
Along with the routes themselves, resources generates named routes for use in controllers and views. map.resources :messages produces the following named routes and helpers:
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)
You can use these helpers instead of url_for or methods that take url_for parameters. For example:
redirect_to :controller => 'messages', :action => 'index' # and <%= link_to "edit this message", :controller => 'messages', :action => 'edit', :id => @message.id %>
now become:
redirect_to messages_url # and <%= link_to "edit this message", edit_message_url(@message) # calls @message.id automatically
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 @message object:
<%= form_tag message_path(@message), :method => :put %>
or
<% form_for :message, @message, :url => message_path(@message), :html => {:method => :put} do |f| %>
or
<% form_for @message do |f| %>
which takes into account whether @message is a new record or not and generates the path and method accordingly.
The resources method accepts the following options to customize the resulting routes:
# products_path == '/productos'
map.resources :products, :as => 'productos' do |product|
# product_reviews_path(product) == '/productos/1234/comentarios'
product.resources :product_reviews, :as => 'comentarios'
end
You may directly specify the routing association with has_one and has_many like:
map.resources :notes, :has_one => :author, :has_many => [:comments, :attachments]
This is the same as:
map.resources :notes do |notes|
notes.resource :author
notes.resources :comments
notes.resources :attachments
end
# new_products_path == '/productos/nuevo'
map.resources :products, :as => 'productos', :path_names => { :new => 'nuevo', :edit => 'editar' }
You can also set default action names from an environment, like this:
config.action_controller.resources_path_names = { :new => 'nuevo', :edit => 'editar' }
Weblog comments usually belong to a post, so you might use resources like:
map.resources :articles map.resources :comments, :path_prefix => '/articles/:article_id'
You can nest resources calls to set this automatically:
map.resources :articles do |article|
article.resources :comments
end
The comment resources work the same, but must now include a value for :article_id.
article_comments_url(@article) article_comment_url(@article, @comment) article_comments_url(:article_id => @article) article_comment_url(:article_id => @article, :id => @comment)
map.resources :tags, :path_prefix => '/books/:book_id', :name_prefix => 'book_' map.resources :tags, :path_prefix => '/toys/:toy_id', :name_prefix => 'toy_'
You may also use :name_prefix to override the generic named routes in a nested resource:
map.resources :articles do |article|
article.resources :comments, :name_prefix => nil
end
This will yield named resources like so:
comments_url(@article) comment_url(@article, @comment)
If map.resources is called with multiple resources, they all get the same options applied.
Examples:
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"
The resources method sets HTTP method restrictions on the routes it generates. For example, making an HTTP POST on new_message_url will raise a RoutingError exception. The default route in config/routes.rb overrides this and allows invalid HTTP methods for resource routes.