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
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
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.
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
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
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
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"}
The :path, :as, :module, :shallow_path and :shallow_prefix all default to the name of the namespace.
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
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
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.
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
Used to route /photos (without the prefix /admin) to Admin::PostsController:
If you want to route /posts (without the prefix /admin) to Admin::PostsController, you could use
scope :module => "admin" do resources :posts end
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’
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
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
# File lib/action_dispatch/routing/mapper.rb, line 686 686: def merge_as_scope(parent, child) 687: parent ? "#{parent}_#{child}" : child 688: end
# 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
# File lib/action_dispatch/routing/mapper.rb, line 706 706: def merge_constraints_scope(parent, child) 707: merge_options_scope(parent, child) 708: end
# File lib/action_dispatch/routing/mapper.rb, line 698 698: def merge_controller_scope(parent, child) 699: child 700: end
# File lib/action_dispatch/routing/mapper.rb, line 710 710: def merge_defaults_scope(parent, child) 711: merge_options_scope(parent, child) 712: end
# File lib/action_dispatch/routing/mapper.rb, line 694 694: def merge_module_scope(parent, child) 695: parent ? "#{parent}/#{child}" : child 696: end
# 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
# 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
# File lib/action_dispatch/routing/mapper.rb, line 678 678: def merge_path_scope(parent, child) 679: Mapper.normalize_path("#{parent}/#{child}") 680: end
# 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
# File lib/action_dispatch/routing/mapper.rb, line 690 690: def merge_shallow_prefix_scope(parent, child) 691: parent ? "#{parent}_#{child}" : child 692: end
# File lib/action_dispatch/routing/mapper.rb, line 724 724: def merge_shallow_scope(parent, child) 725: child ? true : false 726: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.