Module: ActionDispatch::Routing::Mapper::Resources

Relationships & Source Files
Namespace Children
Classes: `Resource`, `SingletonResource`
Extension / Inclusion / Inheritance Descendants
Included In: `::ActionDispatch::Routing::Mapper`
Defined in:	actionpack/lib/action_dispatch/routing/mapper.rb

Overview

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: /[^\/]+/

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

Constant Summary

CANONICAL_ACTIONS =
# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1309
```
%w(index create new show update destroy)
```
RESOURCE_OPTIONS =
# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1308
```
[:as, :controller, :path, :only, :except, :param, :concerns]
```
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.

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1307
```
[:new, :collection, :member]
```

Instance Attribute Summary

#shallow readonly
#shallow? ⇒ Boolean readonly
#api_only? ⇒ Boolean readonly private
#nested_scope? ⇒ Boolean readonly private
#param_constraint? ⇒ Boolean readonly private
#resource_method_scope? ⇒ Boolean readonly private
#resource_scope? ⇒ Boolean readonly private

Instance Method Summary

#collection(&block)

To add a route to the collection:
#draw(name)

Loads another routes file with the given name located inside the config/routes directory.
#match(*path_or_actions, as: DEFAULT, via: nil, to: nil, controller: nil, action: nil, on: nil, defaults: nil, constraints: nil, anchor: nil, format: nil, path: nil, internal: nil, **mapping, &block)

Matches a URL pattern to one or more routes.
#member(&block)

To add a member route, add a member block into the resource block:
#namespace(name, deprecated_options = nil, as: DEFAULT, path: DEFAULT, shallow_path: DEFAULT, shallow_prefix: DEFAULT, **options, &block)

See Scoping#namespace.
#nested(&block)
#new(&block)
#resource(*resources, concerns: nil, **options, &block)

Sometimes, you have a resource that clients always look up without referencing an ID.
#resources(*resources, concerns: nil, **options, &block)

In Rails, a resourceful route provides a mapping between HTTP verbs and URLs and controller actions.
#resources_path_names(options)
#root(path, options = {})

You can specify what ::Rails should route “/” to with the root method:
#action_options?(options) ⇒ Boolean private
#action_path(name) private
#add_route(action, controller, as, options_action, _path, to, via, formatted, anchor, options_constraints, internal, options_mapping) private
#applicable_actions_for(method) private
#apply_action_options(method, options) private
#apply_common_behavior_for(method, resources, shallow: nil, **options, &block) private
#canonical_action?(action) ⇒ Boolean private
#decomposed_match(path, controller, as, action, _path, to, via, formatted, anchor, options_constraints, internal, options_mapping, on = nil) private
#get_to_from_path(path, to, action) private
#map_match(path_or_action, constraints: nil, anchor: nil, format: nil, path: nil, as: DEFAULT, via: nil, to: nil, controller: nil, action: nil, on: nil, internal: nil, mapping: nil) private
#match_root_route(options) private
#name_for_action(as, action) private
#nested_options private
#param_constraint readonly private
#parent_resource private
#path_for_action(action, path) private
#path_scope(path) private
#prefix_name_for_action(as, action) private
#resource_scope(resource, &block) readonly private
#scope_action_options(method) private
#set_member_mappings_for_resource private
#shallow_nesting_depth private
#shallow_scope private
#using_match_shorthand?(path) ⇒ Boolean private
#with_scope_level(kind) private

Instance Attribute Details

#api_only? ⇒ `Boolean` (readonly, private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2126


def api_only? # :doc:
  @set.api_only?
end

#nested_scope? ⇒ `Boolean` (readonly, private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2005


def nested_scope?
  @scope.nested?
end

#param_constraint? ⇒ `Boolean` (readonly, private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2039


def param_constraint?
  @scope[:constraints] && @scope[:constraints][parent_resource.param].is_a?(Regexp)
end

#resource_method_scope? ⇒ `Boolean` (readonly, private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2001


def resource_method_scope?
  @scope.resource_method_scope?
end

#resource_scope? ⇒ `Boolean` (readonly, private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1997


def resource_scope?
  @scope.resource_scope?
end

#shallow (readonly)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1788


def shallow
  @scope = @scope.new(shallow: true)
  yield
ensure
  @scope = @scope.parent
end

#shallow? ⇒ `Boolean` (readonly)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1795


def shallow?
  !parent_resource.singleton? && @scope[:shallow]
end

Instance Method Details

#action_options?(options) ⇒ `Boolean` (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1974


def action_options?(options)
  options[:only] || options[:except]
end

#action_path(name) (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2072


def action_path(name)
  @scope[:path_names][name.to_sym] || name
end

#add_route(action, controller, as, options_action, _path, to, via, formatted, anchor, options_constraints, internal, options_mapping) (private)

Raises:

(ArgumentError)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2201


def add_route(action, controller, as, options_action, _path, to, via, formatted, anchor, options_constraints, internal, options_mapping)
  path = path_for_action(action, _path)
  raise ArgumentError, "path is required" if path.blank?

  action = action.to_s

  default_action = options_action || @scope[:action]

  if /^[\w\-\/]+$/.match?(action)
    default_action ||= action.tr("-", "_") unless action.include?("/")
  else
    action = nil
  end

  as   = name_for_action(as, action) if as
  path = Mapping.normalize_path URI::RFC2396_PARSER.escape(path), formatted
  ast  = Journey::Parser.parse path

  mapping = Mapping.build(@scope, @set, ast, controller, default_action, to, via, formatted, options_constraints, anchor, internal, options_mapping)
  @set.add_route(mapping, as)
end

#applicable_actions_for(method) (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1988


def applicable_actions_for(method)
  case method
  when :resource
    SingletonResource.default_actions(api_only?)
  when :resources
    Resource.default_actions(api_only?)
  end
end

#apply_action_options(method, options) (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1969


def apply_action_options(method, options)
  return options if action_options? options
  options.merge scope_action_options(method)
end

#apply_common_behavior_for(method, resources, shallow: nil, **options, &block) (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1936


def apply_common_behavior_for(method, resources, shallow: nil, **options, &block)
  if resources.length > 1
    resources.each { |r| public_send(method, r, shallow:, **options, &block) }
    return true
  end

  if shallow
    self.shallow do
      public_send(method, resources.pop, **options, &block)
    end
    return true
  end

  if resource_scope?
    nested { public_send(method, resources.pop, shallow:, **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)
  if !scope_options.empty? || !shallow.nil?
    scope(**scope_options, shallow:) do
      public_send(method, resources.pop, **options, &block)
    end
    return true
  end

  false
end

#canonical_action?(action) ⇒ `Boolean` (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2047


def canonical_action?(action)
  resource_method_scope? && CANONICAL_ACTIONS.include?(action.to_s)
end

#collection(&block)

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.

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1712


def collection(&block)
  unless resource_scope?
    raise ArgumentError, "can't use collection outside resource(s) scope"
  end

  with_scope_level(:collection) do
    path_scope(parent_resource.collection_scope, &block)
  end
end

#decomposed_match(path, controller, as, action, _path, to, via, formatted, anchor, options_constraints, internal, options_mapping, on = nil) (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2186


def decomposed_match(path, controller, as, action, _path, to, via, formatted, anchor, options_constraints, internal, options_mapping, on = nil)
  if on
    send(on) { decomposed_match(path, controller, as, action, _path, to, via, formatted, anchor, options_constraints, internal, options_mapping) }
  else
    case @scope.scope_level
    when :resources
      nested { decomposed_match(path, controller, as, action, _path, to, via, formatted, anchor, options_constraints, internal, options_mapping) }
    when :resource
      member { decomposed_match(path, controller, as, action, _path, to, via, formatted, anchor, options_constraints, internal, options_mapping) }
    else
      add_route(path, controller, as, action, _path, to, via, formatted, anchor, options_constraints, internal, options_mapping)
    end
  end
end

#draw(name)

Loads another routes file with the given name located inside the config/routes directory. In that file, you can use the normal routing DSL, but *do not* surround it with a Rails.application.routes.draw block.

# config/routes.rb
Rails.application.routes.draw do
  draw :admin                 # Loads {config/routes/admin.rb}
  draw "third_party/some_gem" # Loads {config/routes/third_party/some_gem.rb}
end

# config/routes/admin.rb
namespace :admin do
  resources :accounts
end

# config/routes/third_party/some_gem.rb
mount SomeGem::Engine, at: "/some_gem"

CAUTION: Use this feature with care. Having multiple routes files can negatively impact discoverability and readability. For most applications —even those with a few hundred routes — it’s easier for developers to have a single routes file.

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1821


def draw(name)
  path = @draw_paths.find do |_path|
    File.exist? "#{_path}/#{name}.rb"
  end

  unless path
    msg  = "Your router tried to #draw the external file #{name}.rb,\n" \
           "but the file was not found in:\n\n"
    msg += @draw_paths.map { |_path| " * #{_path}" }.join("\n")
    raise ArgumentError, msg
  end

  route_path = "#{path}/#{name}.rb"
  instance_eval(File.read(route_path), route_path.to_s)
end

#get_to_from_path(path, to, action) (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2171


def get_to_from_path(path, to, action)
  return to if to || action

  path_without_format = path.sub(/\(\.:format\)$/, "")
  if using_match_shorthand?(path_without_format)
    path_without_format.delete_prefix("/").sub(%r{/([^/]*)$}, '#\1').tr("-", "_")
  else
    nil
  end
end

#map_match(path_or_action, constraints: nil, anchor: nil, format: nil, path: nil, as: DEFAULT, via: nil, to: nil, controller: nil, action: nil, on: nil, internal: nil, mapping: nil) (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2137


def map_match(path_or_action, constraints: nil, anchor: nil, format: nil, path: nil, as: DEFAULT, via: nil, to: nil, controller: nil, action: nil, on: nil, internal: nil, mapping: nil)
  if on && !VALID_ON_OPTIONS.include?(on)
    raise ArgumentError, "Unknown scope #{on.inspect} given to :on"
  end

  if @scope[:to]
    to ||= @scope[:to]
  end

  if @scope[:controller] && @scope[:action]
    to ||= "#{@scope[:controller]}##{@scope[:action]}"
  end

  controller ||= @scope[:controller]
  via = Mapping.check_via Array(via || @scope[:via])
  format ||= @scope[:format] if format.nil?
  anchor ||= true if anchor.nil?
  constraints ||= {}

  case path_or_action
  when String
    if path_or_action && path
      raise ArgumentError, "Ambiguous route definition. Both :path and the route path were specified as strings."
    end
    path = path_or_action
    to = get_to_from_path(path_or_action, to, action)
    decomposed_match(path, controller, as, action, path, to, via, format, anchor, constraints, internal, mapping, on)
  when Symbol
    decomposed_match(path_or_action, controller, as, action, path, to, via, format, anchor, constraints, internal, mapping, on)
  end

  self
end

#match(*path_or_actions, as: DEFAULT, via: nil, to: nil, controller: nil, action: nil, on: nil, defaults: nil, constraints: nil, anchor: nil, format: nil, path: nil, internal: nil, **mapping, &block)

Matches a URL pattern to one or more routes. For more information, see [match](Base#match).

match 'path', to: 'controller#action', via: :post
match 'path', 'otherpath', on: :member, via: :get

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1842


def match(*path_or_actions, as: DEFAULT, via: nil, to: nil, controller: nil, action: nil, on: nil, defaults: nil, constraints: nil, anchor: nil, format: nil, path: nil, internal: nil, **mapping, &block)
  if path_or_actions.grep(Hash).any? && (deprecated_options = path_or_actions.extract_options!)
    as = assign_deprecated_option(deprecated_options, :as, :match) if deprecated_options.key?(:as)
    via ||= assign_deprecated_option(deprecated_options, :via, :match)
    to ||= assign_deprecated_option(deprecated_options, :to, :match)
    controller ||= assign_deprecated_option(deprecated_options, :controller, :match)
    action ||= assign_deprecated_option(deprecated_options, :action, :match)
    on ||= assign_deprecated_option(deprecated_options, :on, :match)
    defaults ||= assign_deprecated_option(deprecated_options, :defaults, :match)
    constraints ||= assign_deprecated_option(deprecated_options, :constraints, :match)
    anchor = assign_deprecated_option(deprecated_options, :anchor, :match) if deprecated_options.key?(:anchor)
    format = assign_deprecated_option(deprecated_options, :format, :match) if deprecated_options.key?(:format)
    path ||= assign_deprecated_option(deprecated_options, :path, :match)
    internal ||= assign_deprecated_option(deprecated_options, :internal, :match)
    assign_deprecated_options(deprecated_options, mapping, :match)
  end

  ActionDispatch.deprecator.warn(<<-MSG.squish) if path_or_actions.count > 1
    Mapping a route with multiple paths is deprecated and
    will be removed in Rails 8.1. Please use multiple method calls instead.
  MSG

  if path_or_actions.none? && mapping.any?
    hash_path, hash_to = mapping.find { |key, _| key.is_a?(String) }
    if hash_path.nil?
      raise ArgumentError, "Route path not specified"
    else
      mapping.delete(hash_path)
    end

    if hash_path
      path_or_actions.push hash_path
      case hash_to
      when Symbol
        action ||= hash_to
      when String
        if hash_to.include?("#")
          to ||= hash_to
        else
          controller ||= hash_to
        end
      else
        to ||= hash_to
      end
    end
  end

  path_or_actions.each do |path_or_action|
    if defaults
      defaults(defaults) { map_match(path_or_action, as:, via:, to:, controller:, action:, on:, constraints:, anchor:, format:, path:, internal:, mapping:, &block) }
    else
      map_match(path_or_action, as:, via:, to:, controller:, action:, on:, constraints:, anchor:, format:, path:, internal:, mapping:, &block)
    end
  end
end

#match_root_route(options) (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2223


def match_root_route(options)
  match("/", as: :root, via: :get, **options)
end

#member(&block)

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.

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1733


def member(&block)
  unless resource_scope?
    raise ArgumentError, "can't use member outside resource(s) scope"
  end

  with_scope_level(:member) do
    if shallow?
      shallow_scope {
        path_scope(parent_resource.member_scope, &block)
      }
    else
      path_scope(parent_resource.member_scope, &block)
    end
  end
end

#name_for_action(as, action) (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2088


def name_for_action(as, action)
  prefix = prefix_name_for_action(as, action)
  name_prefix = @scope[:as]

  if parent_resource
    return nil unless as != DEFAULT || action

    collection_name = parent_resource.collection_name
    member_name = parent_resource.member_name
  end

  action_name = @scope.action_name(name_prefix, prefix, collection_name, member_name)
  candidate = action_name.select(&:present?).join("_")

  unless candidate.empty?
    # If a name was not explicitly given, we check if it is valid and return nil in
    # case it isn't. Otherwise, we pass the invalid name forward so the underlying
    # router engine treats it and raises an exception.
    if as == DEFAULT
      candidate unless !candidate.match?(/\A[_a-z]/i) || has_named_route?(candidate)
    else
      candidate
    end
  end
end

#namespace(name, deprecated_options = nil, as: DEFAULT, path: DEFAULT, shallow_path: DEFAULT, shallow_prefix: DEFAULT, **options, &block)

See Scoping#namespace.

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1780


def namespace(name, deprecated_options = nil, as: DEFAULT, path: DEFAULT, shallow_path: DEFAULT, shallow_prefix: DEFAULT, **options, &block)
  if resource_scope?
    nested { super }
  else
    super
  end
end

#nested(&block)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1759


def nested(&block)
  unless resource_scope?
    raise ArgumentError, "can't use nested outside resource(s) scope"
  end

  with_scope_level(:nested) do
    if shallow? && shallow_nesting_depth >= 1
      shallow_scope do
        path_scope(parent_resource.nested_scope) do
          scope(**nested_options, &block)
        end
      end
    else
      path_scope(parent_resource.nested_scope) do
        scope(**nested_options, &block)
      end
    end
  end
end

#nested_options (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2024


def nested_options
  options = { as: parent_resource.member_name }
  options[:constraints] = {
    parent_resource.nested_param => param_constraint
  } if param_constraint?

  options
end

#new(&block)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1749


def new(&block)
  unless resource_scope?
    raise ArgumentError, "can't use new outside resource(s) scope"
  end

  with_scope_level(:new) do
    path_scope(parent_resource.new_scope(action_path(:new)), &block)
  end
end

#param_constraint (readonly, private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2043


def param_constraint
  @scope[:constraints][parent_resource.param]
end

#parent_resource (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1932


def parent_resource
  @scope[:scope_level_resource]
end

#path_for_action(action, path) (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2062


def path_for_action(action, path)
  return "#{@scope[:path]}/#{path}" if path

  if canonical_action?(action)
    @scope[:path].to_s
  else
    "#{@scope[:path]}/#{action_path(action)}"
  end
end

#path_scope(path) (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2130


def path_scope(path)
  @scope = @scope.new(path: merge_path_scope(@scope[:path], path))
  yield
ensure
  @scope = @scope.parent
end

#prefix_name_for_action(as, action) (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2076


def prefix_name_for_action(as, action)
  if as && as != DEFAULT
    prefix = as
  elsif !canonical_action?(action)
    prefix = action
  end

  if prefix && prefix != "/" && !prefix.empty?
    Mapper.normalize_name prefix.to_s.tr("-", "_")
  end
end

#resource(*resources, concerns: nil, **options, &block)

resource :profile

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

GET       /profile/new
GET       /profile
GET       /profile/edit
PATCH/PUT /profile
DELETE    /profile
POST      /profile

If you want instances of a model to work with this resource via record identification (e.g. in form_with or redirect_to), you will need to call [resolve](CustomUrls#resolve):

resource :profile
resolve('Profile') { [:profile] }

# Enables this to work with singular routes:
form_with(model: @profile) {}

Options

Takes same options as [resources](#resources)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1495


def resource(*resources, concerns: nil, **options, &block)
  if resources.grep(Hash).any? && (deprecated_options = resources.extract_options!)
    concerns = assign_deprecated_option(deprecated_options, :concerns, :resource) if deprecated_options.key?(:concerns)
    assign_deprecated_options(deprecated_options, options, :resource)
  end

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

  with_scope_level(:resource) do
    options = apply_action_options :resource, options
    resource_scope(SingletonResource.new(resources.pop, api_only?, @scope[:shallow], **options)) do
      yield if block_given?

      concerns(*concerns) if concerns

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

      set_member_mappings_for_resource

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

  self
end

#resource_scope(resource, &block) (readonly, private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2016


def resource_scope(resource, &block)
  @scope = @scope.new(scope_level_resource: resource)

  controller(resource.resource_scope, &block)
ensure
  @scope = @scope.parent
end

#resources(*resources, concerns: nil, **options, &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
PATCH/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
PATCH/PUT /photos/:photo_id/comments/:id
DELETE    /photos/:photo_id/comments/:id

Options

Takes same options as [match](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}.

Set `shallow: false` on a child resource to ignore a parent's shallow
parameter.

: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          PATCH/PUT /sekret/comments/:id(.:format)
    comment          DELETE    /sekret/comments/:id(.:format)

:shallow_prefix : Prefixes nested shallow route names with specified prefix.

    scope shallow_prefix: "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_sekret_comment     GET       /comments/:id/edit(.:format)
    sekret_comment          GET       /comments/:id(.:format)
    sekret_comment          PATCH/PUT /comments/:id(.:format)
    sekret_comment          DELETE    /comments/:id(.:format)

:format : Allows you to specify the default value for optional format segment or

disable it by supplying {false}.

:param : Allows you to override the default param name of :id in the URL.

Examples

# routes call {Admin::PostsController}
resources :posts, module: "admin"

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

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1668


def resources(*resources, concerns: nil, **options, &block)
  if resources.grep(Hash).any? && (deprecated_options = resources.extract_options!)
    concerns = assign_deprecated_option(deprecated_options, :concerns, :resources) if deprecated_options.key?(:concerns)
    assign_deprecated_options(deprecated_options, options, :resources)
  end

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

  with_scope_level(:resources) do
    options = apply_action_options :resources, options
    resource_scope(Resource.new(resources.pop, api_only?, @scope[:shallow], **options)) do
      yield if block_given?

      concerns(*concerns) if concerns

      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)

      set_member_mappings_for_resource
    end
  end

  self
end

#resources_path_names(options)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1462


def resources_path_names(options)
  @scope[:path_names].merge!(options)
end

#root(path, options = {})

You can specify what ::Rails should route “/” to with the root method:

root to: 'pages#main'

For options, see #match, as root uses it internally.

You can also pass a string which will expand

root 'pages#main'

You should put the root route at the top of config/routes.rb, because this means it will be matched first. As this is the most popular route of most ::Rails applications, this is beneficial.

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1911


def root(path, options = {})
  if path.is_a?(String)
    options[:to] = path
  elsif path.is_a?(Hash) && options.empty?
    options = path
  else
    raise ArgumentError, "must be called with a path and/or options"
  end

  if @scope.resources?
    with_scope_level(:root) do
      path_scope(parent_resource.path) do
        match_root_route(options)
      end
    end
  else
    match_root_route(options)
  end
end

#scope_action_options(method) (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1978


def scope_action_options(method)
  return {} unless @scope[:action_options]

  actions = applicable_actions_for(method)
  @scope[:action_options].dup.tap do |options|
    (options[:only] = Array(options[:only]) & actions) if options[:only]
    (options[:except] = Array(options[:except]) & actions) if options[:except]
  end
end

#set_member_mappings_for_resource (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2114


def set_member_mappings_for_resource # :doc:
  member do
    get :edit if parent_resource.actions.include?(:edit)
    get :show if parent_resource.actions.include?(:show)
    if parent_resource.actions.include?(:update)
      patch :update
      put   :update
    end
    delete :destroy if parent_resource.actions.include?(:destroy)
  end
end

#shallow_nesting_depth (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2033


def shallow_nesting_depth
  @scope.find_all { |node|
    node.frame[:scope_level_resource]
  }.count { |node| node.frame[:scope_level_resource].shallow? }
end

#shallow_scope (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2051


def shallow_scope
  @scope = @scope.new(
    as: @scope[:shallow_prefix],
    path: @scope[:shallow_path],
  )

  yield
ensure
  @scope = @scope.parent
end

#using_match_shorthand?(path) ⇒ `Boolean` (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2182


def using_match_shorthand?(path)
  %r{^/?[-\w]/[-\w/]$}.match?(path)
end

#with_scope_level(kind) (private)

[ GitHub ]

# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 2009


def with_scope_level(kind) # :doc:
  @scope = @scope.new_level(kind)
  yield
ensure
  @scope = @scope.parent
end

Module: ActionDispatch::Routing::Mapper::Resources

Overview

Constant Summary

Instance Attribute Summary

Instance Method Summary

Instance Attribute Details

#api_only? ⇒ Boolean (readonly, private)

#nested_scope? ⇒ Boolean (readonly, private)

#param_constraint? ⇒ Boolean (readonly, private)

#resource_method_scope? ⇒ Boolean (readonly, private)

#resource_scope? ⇒ Boolean (readonly, private)

#shallow (readonly)

#shallow? ⇒ Boolean (readonly)

Instance Method Details

#action_options?(options) ⇒ Boolean (private)

#action_path(name) (private)

#add_route(action, controller, as, options_action, _path, to, via, formatted, anchor, options_constraints, internal, options_mapping) (private)

#applicable_actions_for(method) (private)

#apply_action_options(method, options) (private)

#apply_common_behavior_for(method, resources, shallow: nil, **options, &block) (private)

#canonical_action?(action) ⇒ Boolean (private)

#collection(&block)

#decomposed_match(path, controller, as, action, _path, to, via, formatted, anchor, options_constraints, internal, options_mapping, on = nil) (private)

#draw(name)

#get_to_from_path(path, to, action) (private)

#map_match(path_or_action, constraints: nil, anchor: nil, format: nil, path: nil, as: DEFAULT, via: nil, to: nil, controller: nil, action: nil, on: nil, internal: nil, mapping: nil) (private)

#match(*path_or_actions, as: DEFAULT, via: nil, to: nil, controller: nil, action: nil, on: nil, defaults: nil, constraints: nil, anchor: nil, format: nil, path: nil, internal: nil, **mapping, &block)

#match_root_route(options) (private)

#member(&block)

#name_for_action(as, action) (private)

#namespace(name, deprecated_options = nil, as: DEFAULT, path: DEFAULT, shallow_path: DEFAULT, shallow_prefix: DEFAULT, **options, &block)

#nested(&block)

#nested_options (private)

#new(&block)

#param_constraint (readonly, private)

#parent_resource (private)

#path_for_action(action, path) (private)

#path_scope(path) (private)

#prefix_name_for_action(as, action) (private)

#resource(*resources, concerns: nil, **options, &block)

Options

#resource_scope(resource, &block) (readonly, private)

#resources(*resources, concerns: nil, **options, &block)

Options

Examples

#resources_path_names(options)

#root(path, options = {})

#scope_action_options(method) (private)

#set_member_mappings_for_resource (private)

#shallow_nesting_depth (private)

#shallow_scope (private)

#using_match_shorthand?(path) ⇒ Boolean (private)

#with_scope_level(kind) (private)

#api_only? ⇒ `Boolean` (readonly, private)

#nested_scope? ⇒ `Boolean` (readonly, private)

#param_constraint? ⇒ `Boolean` (readonly, private)

#resource_method_scope? ⇒ `Boolean` (readonly, private)

#resource_scope? ⇒ `Boolean` (readonly, private)

#shallow? ⇒ `Boolean` (readonly)

#action_options?(options) ⇒ `Boolean` (private)

#canonical_action?(action) ⇒ `Boolean` (private)

#using_match_shorthand?(path) ⇒ `Boolean` (private)