Resource routing allows you to quickly declare all of the common routes for a given resourceful controller. Instead of declaring separate routes for your index, show, new, edit, create, update and destroy actions, a resourceful route declares them in a single line of code:

resources :photos

Sometimes, you have a resource that clients always look up without referencing an ID. A common example, /profile always shows the profile of the currently logged in user. In this case, you can use a singular resource to map /profile (rather than /profile/:id) to the show action.

resource :profile

It’s common to have resources that are logically children of other resources:

resources :magazines do
  resources :ads
end

You may wish to organize groups of controllers under a namespace. Most commonly, you might group a number of administrative controllers under an admin namespace. You would place these controllers under the app/controllers/admin directory, and you can group them together in your router:

namespace "admin" do
  resources :posts, :comments
end

By default the :id parameter doesn’t accept dots. If you need to use dots as part of the :id parameter add a constraint which overrides this restriction, e.g:

resources :articles, :id => %r[^\/]+/

This allows any character other than a slash as part of your :id.

Methods
C
M
N
R
S
W
Constants
VALID_ON_OPTIONS = [:new, :collection, :member]
 

CANONICAL_ACTIONS holds all actions that does not need a prefix or a path appended since they fit properly in their scope level.
RESOURCE_OPTIONS = [:as, :controller, :path, :only, :except]
 
CANONICAL_ACTIONS = %w(index create new show update destroy)
 
Instance Public methods
collection()

To add a route to the collection:

resources :photos do
  collection do
    get 'search'
  end
end

This will enable Rails to recognize paths such as /photos/search with GET, and route to the search action of PhotosController. It will also create the search_photos_url and search_photos_path route helpers.

Source: show | on GitHub 

# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1164
def collection
  unless resource_scope?
    raise ArgumentError, "can't use collection outside resource(s) scope"
  end

  with_scope_level(:collection) do
    scope(parent_resource.collection_scope) do
      yield
    end
  end
end
match(path, *rest)

Source: show | on GitHub 

# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1252
def match(path, *rest)
  if rest.empty? && Hash === path
    options  = path
    path, to = options.find { |name, value| name.is_a?(String) }
    options[:to] = to
    options.delete(path)
    paths = [path]
  else
    options = rest.pop || {}
    paths = [path] + rest
  end

  options[:anchor] = true unless options.key?(:anchor)

  if options[:on] && !VALID_ON_OPTIONS.include?(options[:on])
    raise ArgumentError, "Unknown scope #{on.inspect} given to :on"
  end

  paths.each { |_path| decomposed_match(_path, options.dup) }
  self
end
member()

To add a member route, add a member block into the resource block:

resources :photos do
  member do
    get 'preview'
  end
end

This will recognize /photos/1/preview with GET, and route to the preview action of PhotosController. It will also create the preview_photo_url and preview_photo_path helpers.

Source: show | on GitHub 

# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1187
def member
  unless resource_scope?
    raise ArgumentError, "can't use member outside resource(s) scope"
  end

  with_scope_level(:member) do
    scope(parent_resource.member_scope) do
      yield
    end
  end
end
namespace(path, options = {})

See ActionDispatch::Routing::Mapper::Scoping#namespace

Source: show | on GitHub 

# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1234
def namespace(path, options = {})
  if resource_scope?
    nested { super }
  else
    super
  end
end
nested()

Source: show | on GitHub 

# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1211
def nested
  unless resource_scope?
    raise ArgumentError, "can't use nested outside resource(s) scope"
  end

  with_scope_level(:nested) do
    if shallow?
      with_exclusive_scope do
        if @scope[:shallow_path].blank?
          scope(parent_resource.nested_scope, nested_options) { yield }
        else
          scope(@scope[:shallow_path], :as => @scope[:shallow_prefix]) do
            scope(parent_resource.nested_scope, nested_options) { yield }
          end
        end
      end
    else
      scope(parent_resource.nested_scope, nested_options) { yield }
    end
  end
end
new()

Source: show | on GitHub 

# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1199
def new
  unless resource_scope?
    raise ArgumentError, "can't use new outside resource(s) scope"
  end

  with_scope_level(:new) do
    scope(parent_resource.new_scope(action_path(:new))) do
      yield
    end
  end
end
resource(*resources, &block)

Sometimes, you have a resource that clients always look up without referencing an ID. A common example, /profile always shows the profile of the currently logged in user. In this case, you can use a singular resource to map /profile (rather than /profile/:id) to the show action:

resource :geocoder

creates six different routes in your application, all mapping to the GeoCoders controller (note that the controller is named after the plural):

GET     /geocoder/new
POST    /geocoder
GET     /geocoder
GET     /geocoder/edit
PUT     /geocoder
DELETE  /geocoder

Options

Takes same options as resources.

Source: show | on GitHub 

# File actionpack/lib/action_dispatch/routing/mapper.rb, line 984
def resource(*resources, &block)
  options = resources.extract_options!

  if apply_common_behavior_for(:resource, resources, options, &block)
    return self
  end

  resource_scope(:resource, SingletonResource.new(resources.pop, options)) do
    yield if block_given?

    collection do
      post :create
    end if parent_resource.actions.include?(:create)

    new do
      get :new
    end if parent_resource.actions.include?(:new)

    member do
      get    :edit if parent_resource.actions.include?(:edit)
      get    :show if parent_resource.actions.include?(:show)
      put    :update if parent_resource.actions.include?(:update)
      delete :destroy if parent_resource.actions.include?(:destroy)
    end
  end

  self
end
resources(*resources, &block)

In Rails, a resourceful route provides a mapping between HTTP verbs and URLs and controller actions. By convention, each action also maps to particular CRUD operations in a database. A single entry in the routing file, such as

resources :photos

creates seven different routes in your application, all mapping to the Photos controller:

GET     /photos
GET     /photos/new
POST    /photos
GET     /photos/:id
GET     /photos/:id/edit
PUT     /photos/:id
DELETE  /photos/:id

Resources can also be nested infinitely by using this block syntax:

resources :photos do
  resources :comments
end

This generates the following comments routes:

GET     /photos/:photo_id/comments
GET     /photos/:photo_id/comments/new
POST    /photos/:photo_id/comments
GET     /photos/:photo_id/comments/:id
GET     /photos/:photo_id/comments/:id/edit
PUT     /photos/:photo_id/comments/:id
DELETE  /photos/:photo_id/comments/:id

Options

Takes same options as Base#match as well as:

:path_names

Allows you to change the segment component of the edit and new actions. Actions not specified are not changed.

resources :posts, :path_names => { :new => "brand_new" }

The above example will now change /posts/new to /posts/brand_new

:path

Allows you to change the path prefix for the resource.

resources :posts, :path => 'postings'

The resource and all segments will now route to /postings instead of /posts

:only

Only generate routes for the given actions.

resources :cows, :only => :show
resources :cows, :only => [:show, :index]
:except

Generate all routes except for the given actions.

resources :cows, :except => :show
resources :cows, :except => [:show, :index]
:shallow

Generates shallow routes for nested resource(s). When placed on a parent resource, generates shallow routes for all nested resources.

resources :posts, :shallow => true do
  resources :comments
end

Is the same as:

resources :posts do
  resources :comments, :except => [:show, :edit, :update, :destroy]
end
resources :comments, :only => [:show, :edit, :update, :destroy]

This allows URLs for resources that otherwise would be deeply nested such as a comment on a blog post like /posts/a-long-permalink/comments/1234 to be shortened to just /comments/1234.

:shallow_path

Prefixes nested shallow routes with the specified path.

scope :shallow_path => "sekret" do
  resources :posts do
    resources :comments, :shallow => true
  end
end

The comments resource here will have the following routes generated for it:

post_comments    GET    /posts/:post_id/comments(.:format)
post_comments    POST   /posts/:post_id/comments(.:format)
new_post_comment GET    /posts/:post_id/comments/new(.:format)
edit_comment     GET    /sekret/comments/:id/edit(.:format)
comment          GET    /sekret/comments/:id(.:format)
comment          PUT    /sekret/comments/:id(.:format)
comment          DELETE /sekret/comments/:id(.:format)

Examples

# routes call <tt>Admin::PostsController</tt>
resources :posts, :module => "admin"

# resource actions are at /admin/posts.
resources :posts, :path => "admin/posts"

Source: show | on GitHub 

# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1122
def resources(*resources, &block)
  options = resources.extract_options!

  if apply_common_behavior_for(:resources, resources, options, &block)
    return self
  end

  resource_scope(:resources, Resource.new(resources.pop, options)) do
    yield if block_given?

    collection do
      get  :index if parent_resource.actions.include?(:index)
      post :create if parent_resource.actions.include?(:create)
    end

    new do
      get :new
    end if parent_resource.actions.include?(:new)

    member do
      get    :edit if parent_resource.actions.include?(:edit)
      get    :show if parent_resource.actions.include?(:show)
      put    :update if parent_resource.actions.include?(:update)
      delete :destroy if parent_resource.actions.include?(:destroy)
    end
  end

  self
end
resources_path_names(options)

Source: show | on GitHub 

# File actionpack/lib/action_dispatch/routing/mapper.rb, line 959
def resources_path_names(options)
  @scope[:path_names].merge!(options)
end
root(options={})

Source: show | on GitHub 

# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1309
def root(options={})
  if @scope[:scope_level] == :resources
    with_scope_level(:root) do
      scope(parent_resource.path) do
        super(options)
      end
    end
  else
    super(options)
  end
end
shallow()

Source: show | on GitHub 

# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1242
def shallow
  scope(:shallow => true, :shallow_path => @scope[:path]) do
    yield
  end
end
shallow?()

Source: show | on GitHub 

# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1248
def shallow?
  parent_resource.instance_of?(Resource) && @scope[:shallow]
end
Instance Protected methods
with_exclusive_scope()

Source: show | on GitHub 

# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1377
def with_exclusive_scope
  begin
    old_name_prefix, old_path = @scope[:as], @scope[:path]
    @scope[:as], @scope[:path] = nil, nil

    with_scope_level(:exclusive) do
      yield
    end
  ensure
    @scope[:as], @scope[:path] = old_name_prefix, old_path
  end
end
with_scope_level(kind, resource = parent_resource)

Source: show | on GitHub 

# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1390
def with_scope_level(kind, resource = parent_resource)
  old, @scope[:scope_level] = @scope[:scope_level], kind
  old_resource, @scope[:scope_level_resource] = @scope[:scope_level_resource], resource
  yield
ensure
  @scope[:scope_level] = old
  @scope[:scope_level_resource] = old_resource
end