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/photos
  GET       /admin/photos/new
  POST    /admin/photos
  GET       /admin/photos/1
  GET       /admin/photos/1/edit
  PUT       /admin/photos/1
  DELETE  /admin/photos/1

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

  scope :module => "admin" do
    resources :posts, :comments
  end

or, for a single case

  resources :posts, :module => "admin"

If you want to route /admin/photos to PostsController

(without the Admin

module prefix), you could use

  scope "/admin" do
    resources :posts, :comments
  end

or, for a single case

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

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/photos
  GET       /admin/photos/new
  POST    /admin/photos
  GET       /admin/photos/1
  GET       /admin/photos/1/edit
  PUT       /admin/photos/1
  DELETE  /admin/photos/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 resrict other parameters:

  resources :posts do
    constraints(:post_id => /\d+\.\d+) do
      resources :comments
    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 critera:

   constraints(lambda { |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 660
660:         def constraints(constraints = {})
661:           scope(:constraints => constraints) { yield }
662:         end

controller(controller, options={}) click to toggle source

Scopes routes to a specific controller

Example:

  controller "food" do
    match "bacon", :action => "bacon"
  end

     # File lib/action_dispatch/routing/mapper.rb, line 542
542:         def controller(controller, options={})
543:           options[:controller] = controller
544:           scope(options) { yield }
545:         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 669
669:         def defaults(defaults = {})
670:           scope(:defaults => defaults) { yield }
671:         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)          {:action=>"index", :controller=>"admin/posts"}
    admin_posts POST   /admin/posts(.:format)          {:action=>"create", :controller=>"admin/posts"}
 new_admin_post GET    /admin/posts/new(.:format)      {:action=>"new", :controller=>"admin/posts"}

edit_admin_post GET /admin/posts/:id/edit(.:format) {:action=>“edit”, :controller=>“admin/posts“}

     admin_post GET    /admin/posts/:id(.:format)      {:action=>"show", :controller=>"admin/posts"}
     admin_post PUT    /admin/posts/:id(.:format)      {:action=>"update", :controller=>"admin/posts"}
     admin_post DELETE /admin/posts/:id(.:format)      {:action=>"destroy", :controller=>"admin/posts"}

Supported options

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

:path

The path prefix for the routes.

namespace :admin, :path => “sekret” do

  resources :posts

end

All routes for the above resources will be accessible through /sekret/posts, rather than /admin/posts

:module

The namespace for the controllers.

namespace :admin, :module => “sekret” do

  resources :posts

end

The PostsController here should go in the Sekret namespace and so it should be defined like this:

class Sekret::PostsController < ApplicationController

  # code go here

end

:as

Changes the name used in routing helpers for this namespace.

  namespace :admin, :as => "sekret" do
    resources :posts
  end

Routing helpers such as admin_posts_path will now be sekret_posts_path.

:shallow_path: See the scope method.

     # File lib/action_dispatch/routing/mapper.rb, line 599
599:         def namespace(path, options = {})
600:           path = path.to_s
601:           options = { :path => path, :as => path, :module => path,
602:                       :shallow_path => path, :shallow_prefix => path }.merge!(options)
603:           scope(options) { yield }
604:         end

scope(*args) click to toggle source

Used to route /photos (without the prefix /admin) to Admin::PostsController:

Supported options

:module

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

  scope :module => "admin" do
    resources :posts
  end

:path

If you want to prefix the route, you could use

  scope :path => "/admin" do
    resources :posts
  end

This will prefix all of the posts resource’s requests with ’/admin’

:as

Prefixes the routing helpers in this scope with the specified label.

  scope :as => "sekret" do
    resources :posts
  end

Helpers such as posts_path will now be sekret_posts_path

:shallow_path

  Prefixes nested shallow routes with the specified path.

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

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

    post_comments    GET    /sekret/posts/:post_id/comments(.:format)
    post_comments    POST   /sekret/posts/:post_id/comments(.:format)
    new_post_comment GET    /sekret/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)

     # File lib/action_dispatch/routing/mapper.rb, line 495
495:         def scope(*args)
496:           options = args.extract_options!
497:           options = options.dup
498: 
499:           if name_prefix = options.delete(:name_prefix)
500:             options[:as] ||= name_prefix
501:             ActiveSupport::Deprecation.warn ":name_prefix was deprecated in the new router syntax. Use :as instead.", caller
502:           end
503: 
504:           options[:path] = args.first if args.first.is_a?(String)
505:           recover = {}
506: 
507:           options[:constraints] ||= {}
508:           unless options[:constraints].is_a?(Hash)
509:             block, options[:constraints] = options[:constraints], {}
510:           end
511: 
512:           scope_options.each do |option|
513:             if value = options.delete(option)
514:               recover[option] = @scope[option]
515:               @scope[option]  = send("merge_#{option}_scope", @scope[option], value)
516:             end
517:           end
518: 
519:           recover[:block] = @scope[:blocks]
520:           @scope[:blocks] = merge_blocks_scope(@scope[:blocks], block)
521: 
522:           recover[:options] = @scope[:options]
523:           @scope[:options]  = merge_options_scope(@scope[:options], options)
524: 
525:           yield
526:           self
527:         ensure
528:           scope_options.each do |option|
529:             @scope[option] = recover[option] if recover.has_key?(option)
530:           end
531: 
532:           @scope[:options] = recover[:options]
533:           @scope[:blocks]  = recover[:block]
534:         end

Private Instance Methods

merge_as_scope(parent, child) click to toggle source

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

merge_blocks_scope(parent, child) click to toggle source

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

merge_constraints_scope(parent, child) click to toggle source

     # File lib/action_dispatch/routing/mapper.rb, line 706
706:           def merge_constraints_scope(parent, child)
707:             merge_options_scope(parent, child)
708:           end

merge_controller_scope(parent, child) click to toggle source

     # File lib/action_dispatch/routing/mapper.rb, line 698
698:           def merge_controller_scope(parent, child)
699:             child
700:           end

merge_defaults_scope(parent, child) click to toggle source

     # File lib/action_dispatch/routing/mapper.rb, line 710
710:           def merge_defaults_scope(parent, child)
711:             merge_options_scope(parent, child)
712:           end

merge_module_scope(parent, child) click to toggle source

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

merge_options_scope(parent, child) click to toggle source

     # File lib/action_dispatch/routing/mapper.rb, line 720
720:           def merge_options_scope(parent, child)
721:             (parent || {}).except(*override_keys(child)).merge(child)
722:           end

merge_path_names_scope(parent, child) click to toggle source

     # File lib/action_dispatch/routing/mapper.rb, line 702
702:           def merge_path_names_scope(parent, child)
703:             merge_options_scope(parent, child)
704:           end

merge_path_scope(parent, child) click to toggle source

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

merge_shallow_path_scope(parent, child) click to toggle source

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

merge_shallow_prefix_scope(parent, child) click to toggle source

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

merge_shallow_scope(parent, child) click to toggle source

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

override_keys(child) click to toggle source

     # File lib/action_dispatch/routing/mapper.rb, line 728
728:           def override_keys(child)
729:             child.key?(:only) || child.key?(:except) ? [:only, :except] : []
730:           end

scope_options() click to toggle source

     # File lib/action_dispatch/routing/mapper.rb, line 674
674:           def scope_options
675:             @scope_options ||= private_methods.grep(/^merge_(.+)_scope$/) { $1.to_sym }
676:           end

Home Classes Methods

In Files

Methods

Class Index

ActionDispatch::Routing::Mapper::Scoping

Public Instance Methods

Parameter Restriction

Restricting based on IP

Dynamic request matching

Supported options

Supported options

Private Instance Methods