Module | ActionController::Resources
In: | lib/action_controller/resources.rb

### Methods

resource resources

### Public Instance methods

resource(*entities, &block)

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

resources(*entities, &block)

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:

- `: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
        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)

- `: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"

[Validate]