module ActionDispatch::Routing::Mapper::Scoping

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

This will create a number of routes for each of the posts and comments controller. For Admin::PostsController, Rails will create:

GET       /admin/posts
GET       /admin/posts/new
POST      /admin/posts
GET       /admin/posts/1
GET       /admin/posts/1/edit
PATCH/PUT /admin/posts/1
DELETE    /admin/posts/1

If you want to route /posts (without the prefix /admin) to Admin::PostsController, you could use

scope module: "admin" do
  resources :posts
end

or, for a single case

resources :posts, module: "admin"

If you want to route /admin/posts to PostsController (without the Admin:: module prefix), you could use

scope "/admin" do
  resources :posts
end

or, for a single case

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

In each of these cases, the named routes remain the same as if you did not use scope. In the last case, the following paths map to PostsController:

GET       /admin/posts
GET       /admin/posts/new
POST      /admin/posts
GET       /admin/posts/1
GET       /admin/posts/1/edit
PATCH/PUT /admin/posts/1
DELETE    /admin/posts/1

Public Instance Methods

constraints(constraints = {}) { || ... } click to toggle source

Parameter Restriction¶ ↑

Allows you to constrain the nested routes based on a set of rules. For instance, in order to change the routes to allow for a dot character in the id parameter:

constraints(id: /\d+\.\d+/) do
  resources :posts
end

Now routes such as /posts/1 will no longer be valid, but /posts/1.1 will be. The id parameter must match the constraint passed in for this example.

You may use this to also restrict other parameters:

resources :posts do
  constraints(post_id: /\d+\.\d+/) do
    resources :comments
  end
end

Restricting based on IP¶ ↑

Routes can also be constrained to an IP or a certain range of IP addresses:

constraints(ip: /192\.168\.\d+\.\d+/) do
  resources :posts
end

Any user connecting from the 192.168.* range will be able to see this resource, where as any user connecting outside of this range will be told there is no such route.

Dynamic request matching¶ ↑

Requests to routes can be constrained based on specific criteria:

constraints(-> (req) { req.env["HTTP_USER_AGENT"] =~ /iPhone/ }) do
  resources :iphones
end

You are able to move this logic out into a class if it is too complex for routes. This class must have a matches? method defined on it which either returns true if the user should be given access to that route, or false if the user should not.

class Iphone
  def self.matches?(request)
    request.env["HTTP_USER_AGENT"] =~ /iPhone/
  end
end

An expected place for this code would be lib/constraints.

This class is then used like this:

constraints(Iphone) do
  resources :iphones
end

# File lib/action_dispatch/routing/mapper.rb, line 995
def constraints(constraints = {})
  scope(constraints: constraints) { yield }
end

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

Scopes routes to a specific controller

controller "food" do
  match "bacon", action: :bacon, via: :get
end

# File lib/action_dispatch/routing/mapper.rb, line 880
def controller(controller)
  @scope = @scope.new(controller: controller)
  yield
ensure
  @scope = @scope.parent
end

defaults(defaults = {}) { || ... } click to toggle source

Allows you to set default parameters for a route, such as this:

defaults id: 'home' do
  match 'scoped_pages/(:id)', to: 'pages#show'
end

Using this, the :id parameter here will default to 'home'.

# File lib/action_dispatch/routing/mapper.rb, line 1004
def defaults(defaults = {})
  @scope = @scope.new(defaults: merge_defaults_scope(@scope[:defaults], defaults))
  yield
ensure
  @scope = @scope.parent
end

namespace(path, options = {}) { || ... } click to toggle source

Scopes routes to a specific namespace. For example:

namespace :admin do
  resources :posts
end

This generates the following routes:

    admin_posts GET       /admin/posts(.:format)          admin/posts#index
    admin_posts POST      /admin/posts(.:format)          admin/posts#create
 new_admin_post GET       /admin/posts/new(.:format)      admin/posts#new
edit_admin_post GET       /admin/posts/:id/edit(.:format) admin/posts#edit
     admin_post GET       /admin/posts/:id(.:format)      admin/posts#show
     admin_post PATCH/PUT /admin/posts/:id(.:format)      admin/posts#update
     admin_post DELETE    /admin/posts/:id(.:format)      admin/posts#destroy

Options¶ ↑

The :path, :as, :module, :shallow_path and :shallow_prefix options all default to the name of the namespace.

For options, see Base#match. For :shallow_path option, see Resources#resources.

# accessible through /sekret/posts rather than /admin/posts
namespace :admin, path: "sekret" do
  resources :posts
end

# maps to <tt>Sekret::PostsController</tt> rather than <tt>Admin::PostsController</tt>
namespace :admin, module: "sekret" do
  resources :posts
end

# generates +sekret_posts_path+ rather than +admin_posts_path+
namespace :admin, as: "sekret" do
  resources :posts
end

# File lib/action_dispatch/routing/mapper.rb, line 925
def namespace(path, options = {})
  path = path.to_s

  defaults = {
    module:         path,
    as:             options.fetch(:as, path),
    shallow_path:   options.fetch(:path, path),
    shallow_prefix: options.fetch(:as, path)
  }

  path_scope(options.delete(:path) { path }) do
    scope(defaults.merge!(options)) { yield }
  end
end

scope(*args) { || ... } click to toggle source

Scopes a set of routes to the given default options.

Take the following route definition as an example:

scope path: ":account_id", as: "account" do
  resources :projects
end

This generates helpers such as account_projects_path, just like resources does. The difference here being that the routes generated are like /:account_id/projects, rather than /accounts/:account_id/projects.

Options¶ ↑

Takes same options as Base#match and Resources#resources.

# route /posts (without the prefix /admin) to <tt>Admin::PostsController</tt>
scope module: "admin" do
  resources :posts
end

# prefix the posts resource's requests with '/admin'
scope path: "/admin" do
  resources :posts
end

# prefix the routing helper name: +sekret_posts_path+ instead of +posts_path+
scope as: "sekret" do
  resources :posts
end

# File lib/action_dispatch/routing/mapper.rb, line 821
def scope(*args)
  options = args.extract_options!.dup
  scope = {}

  options[:path] = args.flatten.join("/") if args.any?
  options[:constraints] ||= {}

  unless nested_scope?
    options[:shallow_path] ||= options[:path] if options.key?(:path)
    options[:shallow_prefix] ||= options[:as] if options.key?(:as)
  end

  if options[:constraints].is_a?(Hash)
    defaults = options[:constraints].select do |k, v|
      URL_OPTIONS.include?(k) && (v.is_a?(String) || v.is_a?(Integer))
    end

    options[:defaults] = defaults.merge(options[:defaults] || {})
  else
    block, options[:constraints] = options[:constraints], {}
  end

  if options.key?(:only) || options.key?(:except)
    scope[:action_options] = { only: options.delete(:only),
                               except: options.delete(:except) }
  end

  if options.key? :anchor
    raise ArgumentError, "anchor is ignored unless passed to `match`"
  end

  @scope.options.each do |option|
    if option == :blocks
      value = block
    elsif option == :options
      value = options
    else
      value = options.delete(option) { POISON }
    end

    unless POISON == value
      scope[option] = send("merge_#{option}_scope", @scope[option], value)
    end
  end

  @scope = @scope.new scope
  yield
  self
ensure
  @scope = @scope.parent
end

Private Instance Methods

merge_action_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1036
def merge_action_scope(parent, child)
  child
end

merge_as_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1020
def merge_as_scope(parent, child)
  parent ? "#{parent}_#{child}" : child
end

merge_blocks_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1060
def merge_blocks_scope(parent, child)
  merged = parent ? parent.dup : []
  merged << child if child
  merged
end

merge_constraints_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1052
def merge_constraints_scope(parent, child)
  merge_options_scope(parent, child)
end

merge_controller_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1032
def merge_controller_scope(parent, child)
  child
end

merge_defaults_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1056
def merge_defaults_scope(parent, child)
  merge_options_scope(parent, child)
end

merge_format_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1044
def merge_format_scope(parent, child)
  child
end

merge_module_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1028
def merge_module_scope(parent, child)
  parent ? "#{parent}/#{child}" : child
end

merge_options_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1066
def merge_options_scope(parent, child)
  (parent || {}).merge(child)
end

merge_path_names_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1048
def merge_path_names_scope(parent, child)
  merge_options_scope(parent, child)
end

merge_path_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1012
def merge_path_scope(parent, child)
  Mapper.normalize_path("#{parent}/#{child}")
end

merge_shallow_path_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1016
def merge_shallow_path_scope(parent, child)
  Mapper.normalize_path("#{parent}/#{child}")
end

merge_shallow_prefix_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1024
def merge_shallow_prefix_scope(parent, child)
  parent ? "#{parent}_#{child}" : child
end

merge_shallow_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1070
def merge_shallow_scope(parent, child)
  child ? true : false
end

merge_to_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1074
def merge_to_scope(parent, child)
  child
end

merge_via_scope(parent, child) click to toggle source

# File lib/action_dispatch/routing/mapper.rb, line 1040
def merge_via_scope(parent, child)
  child
end