Module | ActionController::Resources |
In: |
lib/action_controller/resources.rb
|
Creates named routes for implementing verb-oriented controllers for a singleton resource. A singleton resource is global to the current user visiting the application, such as a user‘s /account profile.
See map.resources for general conventions. These are the main differences:
- A singular name is given to map.resource. The default controller name is taken from the singular name. - There is no <tt>:collection</tt> option as there is only the singleton resource. - There is no <tt>:singular</tt> option as the singular name is passed to map.resource. - No default index route is created for the singleton resource controller. - When nesting singleton resources, only the singular name is used as the path prefix (example: 'account/messages/1')
Example:
map.resource :account class AccountController < ActionController::Base # POST account_url def create # create an account end # GET new_account_url def new # return an HTML form for describing the new 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 the following named routes and helpers:
Named Route Helpers account account_url, hash_for_account_url, account_path, hash_for_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. 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, :url => message_path(@message), :html => {:method => :put} do |f| %>
The resources method accepts various options, too, to customize the resulting routes:
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_'
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"