Class Index [+]

Quicksearch

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

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.