module ActionDispatch::Routing::Mapper::Resources

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.

Constants

CANONICAL_ACTIONS
RESOURCE_OPTIONS
VALID_ON_OPTIONS

CANONICAL_ACTIONS holds all actions that does not need a prefix or a path appended since they fit properly in their scope level.

Public Instance Methods

collection() { || ... } click to toggle source

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.

# File lib/action_dispatch/routing/mapper.rb, line 1045
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(*args) click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1133
def match(*args)
  options = args.extract_options!.dup
  options[:anchor] = true unless options.key?(:anchor)

  if args.length > 1
    args.each { |path| match(path, options.dup) }
    return self
  end

  on = options.delete(:on)
  if VALID_ON_OPTIONS.include?(on)
    args.push(options)
    return send(on){ match(*args) }
  elsif on
    raise ArgumentError, "Unknown scope #{on.inspect} given to :on"
  end

  if @scope[:scope_level] == :resources
    args.push(options)
    return nested { match(*args) }
  elsif @scope[:scope_level] == :resource
    args.push(options)
    return member { match(*args) }
  end

  action = args.first
  path = path_for_action(action, options.delete(:path))

  if action.to_s =~ %r^[\w\/]+$/
    options[:action] ||= action unless action.to_s.include?("/")
  else
    action = nil
  end

  if options.key?(:as) && !options[:as]
    options.delete(:as)
  else
    options[:as] = name_for_action(options[:as], action)
  end

  super(path, options)
end
member() { || ... } click to toggle source

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.

# File lib/action_dispatch/routing/mapper.rb, line 1068
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 = {}) click to toggle source

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

# File lib/action_dispatch/routing/mapper.rb, line 1115
def namespace(path, options = {})
  if resource_scope?
    nested { super }
  else
    super
  end
end
nested() { || ... } click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1092
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() { || ... } click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1080
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) { || ... } click to toggle source

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
# File lib/action_dispatch/routing/mapper.rb, line 919
def resource(*resources, &block)
  options = resources.extract_options!

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

  resource_scope(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) { || ... } click to toggle source

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/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/:id/comments/new
POST    /photos/:id/comments
GET     /photos/:id/comments/:id
GET     /photos/:id/comments/:id/edit
PUT     /photos/:id/comments/:id
DELETE  /photos/:id/comments/:id

Supported options

:path_names

Allows you to change the paths of the seven default actions. Paths not specified are not changed.

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

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

:module

Set the module where the controller can be found. Defaults to nothing.

resources :posts, :module => "admin"

All requests to the posts resources will now go to +Admin::PostsController+.

:path

Set a path prefix for this resource.

resources :posts, :path => "admin/posts"

All actions for this resource will now be at /admin/posts.

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

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

  resource_scope(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) click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 897
def resources_path_names(options)
  @scope[:path_names].merge!(options)
end
root(options={}) click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1176
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() { || ... } click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1123
def shallow
  scope(:shallow => true) do
    yield
  end
end
shallow?() click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1129
def shallow?
  parent_resource.instance_of?(Resource) && @scope[:shallow]
end

Protected Instance Methods

action_options?(options) click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1224
def action_options?(options)
  options[:only] || options[:except]
end
action_path(name, path = nil) click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1308
def action_path(name, path = nil)
  path || @scope[:path_names][name.to_sym] || name.to_s
end
apply_common_behavior_for(method, resources, options, &block) click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1194
def apply_common_behavior_for(method, resources, options, &block)
  if resources.length > 1
    resources.each { |r| send(method, r, options, &block) }
    return true
  end

  if resource_scope?
    nested { send(method, resources.pop, options, &block) }
    return true
  end

  options.keys.each do |k|
    (options[:constraints] ||= {})[k] = options.delete(k) if options[k].is_a?(Regexp)
  end

  scope_options = options.slice!(*RESOURCE_OPTIONS)
  unless scope_options.empty?
    scope(scope_options) do
      send(method, resources.pop, options, &block)
    end
    return true
  end

  unless action_options?(options)
    options.merge!(scope_action_options) if scope_action_options?
  end

  false
end
canonical_action?(action, flag) click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1289
def canonical_action?(action, flag)
  flag && resource_method_scope? && CANONICAL_ACTIONS.include?(action.to_s)
end
id_constraint() click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1285
def id_constraint
  @scope[:constraints][:id]
end
id_constraint?() click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1281
def id_constraint?
  @scope[:constraints] && @scope[:constraints][:id].is_a?(Regexp)
end
name_for_action(as, action) click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1320
def name_for_action(as, action)
  prefix = prefix_name_for_action(as, action)
  prefix = Mapper.normalize_name(prefix) if prefix
  name_prefix = @scope[:as]

  if parent_resource
    return nil if as.nil? && action.nil?

    collection_name = parent_resource.collection_name
    member_name = parent_resource.member_name
  end

  name = case @scope[:scope_level]
  when :nested
    [name_prefix, prefix]
  when :collection
    [prefix, name_prefix, collection_name]
  when :new
    [prefix, :new, name_prefix, member_name]
  when :member
    [prefix, shallow_scoping? ? @scope[:shallow_prefix] : name_prefix, member_name]
  when :root
    [name_prefix, collection_name, prefix]
  else
    [name_prefix, member_name, prefix]
  end

  candidate = name.select(&:present?).join("_").presence
  candidate unless as.nil? && @set.routes.find { |r| r.name == candidate }
end
nested_options() click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1274
def nested_options
  {}.tap do |options|
    options[:as] = parent_resource.member_name
    options[:constraints] = { "#{parent_resource.singular}_id".to_sym => id_constraint } if id_constraint?
  end
end
path_for_action(action, path) click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1297
def path_for_action(action, path)
  prefix = shallow_scoping? ?
    "#{@scope[:shallow_path]}/#{parent_resource.path}/:id" : @scope[:path]

  path = if canonical_action?(action, path.blank?)
    prefix.to_s
  else
    "#{prefix}/#{action_path(action, path)}"
  end
end
prefix_name_for_action(as, action) click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1312
def prefix_name_for_action(as, action)
  if as
    as.to_s
  elsif !canonical_action?(action, @scope[:scope_level])
    action.to_s
  end
end
resource_method_scope?() click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1240
def resource_method_scope?
  [:collection, :member, :new].include?(@scope[:scope_level])
end
resource_scope(resource) { || ... } click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1266
def resource_scope(resource)
  with_scope_level(resource.is_a?(SingletonResource) ? :resource : :resources, resource) do
    scope(parent_resource.resource_scope) do
      yield
    end
  end
end
resource_scope?() click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1236
def resource_scope?
  [:resource, :resources].include?(@scope[:scope_level])
end
scope_action_options() click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1232
def scope_action_options
  @scope[:options].slice(:only, :except)
end
scope_action_options?() click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1228
def scope_action_options?
  @scope[:options].is_a?(Hash) && (@scope[:options][:only] || @scope[:options][:except])
end
shallow_scoping?() click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1293
def shallow_scoping?
  shallow? && @scope[:scope_level] == :member
end
with_exclusive_scope() { || ... } click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1244
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) { || ... } click to toggle source
# File lib/action_dispatch/routing/mapper.rb, line 1257
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