Creates named routes for implementing verb-oriented controllers. This is useful for implementing REST API‘s, where a single resource has different behavior based on the HTTP verb (method) used to access it.
Example:
map.resources :messages
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
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.
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:
redirect_to :controller => 'messages', :action => 'index' # becomes redirect_to messages_url <%= link_to "edit this message", :controller => 'messages', :action => 'edit', :id => @message.id %> # becomes <%= 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, message_path(@message), :html => {:method => :put} do |f| %>
The resources method accepts various options, too, to customize the resulting routes:
- :controller — specify the controller name for the routes.
- :singular — specify the singular name used in the member routes.
- :path_prefix — set a prefix to the routes with required
route variables. 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 endThe comment resources work the same, but must now include a value for :article_id.
comments_url(@article) comment_url(@article, @comment) comments_url(:article_id => @article) comment_url(:article_id => @article, :id => @comment)
- :name_prefix — define a prefix for all generated routes,
usually ending in an underscore. Use this if you have named routes that may
clash.
map.resources :tags, :path_prefix => '/books/:book_id', :name_prefix => 'book_' map.resources :tags, :path_prefix => '/toys/:toy_id', :name_prefix => 'toy_'
- :collection — add named routes for other actions that operate on the collection. Takes a hash of #{action} => #{method}, where method is :get/:post/:put/:delete or :any if the method does not matter. These routes map to a URL like /messages;rss, with a route of rss_messages_url.
- :member — same as :collection, but for actions that operate on a specific member.
- :new — same as :collection, but for actions that operate on the new resource action.
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"
[ show source ]
# File vendor/rails/actionpack/lib/action_controller/resources.rb, line 215
215: def resources(*entities, &block)
216: options = entities.last.is_a?(Hash) ? entities.pop : { }
217: entities.each { |entity| map_resource entity, options.dup, &block }
218: end