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 => %r[^\/]+/
This allows any character other than a slash as part of your :id.
CANONICAL_ACTIONS holds all actions that does not need a prefix or a path appended since they fit properly in their scope level.
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.
# File lib/action_dispatch/routing/mapper.rb, line 1045 def collection unless resource_scope? raise ArgumentError, "can't use collection outside resource(s) scope" end with_scope_level(:collection) do scope(parent_resource.collection_scope) do yield end end end
# File lib/action_dispatch/routing/mapper.rb, line 1133 def match(*args) options = args.extract_options!.dup options[:anchor] = true unless options.key?(:anchor) if args.length > 1 args.each { |path| match(path, options.dup) } return self end on = options.delete(:on) if VALID_ON_OPTIONS.include?(on) args.push(options) return send(on){ match(*args) } elsif on raise ArgumentError, "Unknown scope #{on.inspect} given to :on" end if @scope[:scope_level] == :resources args.push(options) return nested { match(*args) } elsif @scope[:scope_level] == :resource args.push(options) return member { match(*args) } end action = args.first path = path_for_action(action, options.delete(:path)) if action.to_s =~ %r^[\w\/]+$/ options[:action] ||= action unless action.to_s.include?("/") else action = nil end if options.key?(:as) && !options[:as] options.delete(:as) else options[:as] = name_for_action(options[:as], action) end super(path, options) end
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.
# File lib/action_dispatch/routing/mapper.rb, line 1068 def member unless resource_scope? raise ArgumentError, "can't use member outside resource(s) scope" end with_scope_level(:member) do scope(parent_resource.member_scope) do yield end end end
See ActionDispatch::Routing::Mapper::Scoping#namespace
# File lib/action_dispatch/routing/mapper.rb, line 1115 def namespace(path, options = {}) if resource_scope? nested { super } else super end end
# File lib/action_dispatch/routing/mapper.rb, line 1092 def nested unless resource_scope? raise ArgumentError, "can't use nested outside resource(s) scope" end with_scope_level(:nested) do if shallow? with_exclusive_scope do if @scope[:shallow_path].blank? scope(parent_resource.nested_scope, nested_options) { yield } else scope(@scope[:shallow_path], :as => @scope[:shallow_prefix]) do scope(parent_resource.nested_scope, nested_options) { yield } end end end else scope(parent_resource.nested_scope, nested_options) { yield } end end end
# File lib/action_dispatch/routing/mapper.rb, line 1080 def new unless resource_scope? raise ArgumentError, "can't use new outside resource(s) scope" end with_scope_level(:new) do scope(parent_resource.new_scope(action_path(:new))) do yield end end end
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 :geocoder
creates six different routes in your application, all mapping to the GeoCoders controller (note that the controller is named after the plural):
GET /geocoder/new POST /geocoder GET /geocoder GET /geocoder/edit PUT /geocoder DELETE /geocoder
# File lib/action_dispatch/routing/mapper.rb, line 919 def resource(*resources, &block) options = resources.extract_options! if apply_common_behavior_for(:resource, resources, options, &block) return self end resource_scope(SingletonResource.new(resources.pop, options)) do yield if block_given? collection do post :create end if parent_resource.actions.include?(:create) new do get :new end if parent_resource.actions.include?(:new) member do get :edit if parent_resource.actions.include?(:edit) get :show if parent_resource.actions.include?(:show) put :update if parent_resource.actions.include?(:update) delete :destroy if parent_resource.actions.include?(:destroy) end end self end
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/new POST /photos GET /photos/:id GET /photos/:id/edit 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/:id/comments/new POST /photos/:id/comments GET /photos/:id/comments/:id GET /photos/:id/comments/:id/edit PUT /photos/:id/comments/:id DELETE /photos/:id/comments/:id
Allows you to change the paths of the seven default actions. Paths not specified are not changed.
resources :posts, :path_names => { :new => "brand_new" }
The above example will now change /posts/new to /posts/brand_new
Set the module where the controller can be found. Defaults to nothing.
resources :posts, :module => "admin"
All requests to the posts resources will now go to +Admin::PostsController+.
Set a path prefix for this resource.
resources :posts, :path => "admin/posts"
All actions for this resource will now be at /admin/posts
.
# File lib/action_dispatch/routing/mapper.rb, line 1003 def resources(*resources, &block) options = resources.extract_options! if apply_common_behavior_for(:resources, resources, options, &block) return self end resource_scope(Resource.new(resources.pop, options)) do yield if block_given? 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) member do get :edit if parent_resource.actions.include?(:edit) get :show if parent_resource.actions.include?(:show) put :update if parent_resource.actions.include?(:update) delete :destroy if parent_resource.actions.include?(:destroy) end end self end
# File lib/action_dispatch/routing/mapper.rb, line 897 def resources_path_names(options) @scope[:path_names].merge!(options) end
# File lib/action_dispatch/routing/mapper.rb, line 1176 def root(options={}) if @scope[:scope_level] == :resources with_scope_level(:root) do scope(parent_resource.path) do super(options) end end else super(options) end end
# File lib/action_dispatch/routing/mapper.rb, line 1123 def shallow scope(:shallow => true) do yield end end
# File lib/action_dispatch/routing/mapper.rb, line 1129 def shallow? parent_resource.instance_of?(Resource) && @scope[:shallow] end
# File lib/action_dispatch/routing/mapper.rb, line 1224 def action_options?(options) options[:only] || options[:except] end
# File lib/action_dispatch/routing/mapper.rb, line 1308 def action_path(name, path = nil) path || @scope[:path_names][name.to_sym] || name.to_s end
# File lib/action_dispatch/routing/mapper.rb, line 1194 def apply_common_behavior_for(method, resources, options, &block) if resources.length > 1 resources.each { |r| send(method, r, options, &block) } return true end if resource_scope? nested { send(method, resources.pop, 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) unless scope_options.empty? scope(scope_options) do send(method, resources.pop, options, &block) end return true end unless action_options?(options) options.merge!(scope_action_options) if scope_action_options? end false end
# File lib/action_dispatch/routing/mapper.rb, line 1289 def canonical_action?(action, flag) flag && resource_method_scope? && CANONICAL_ACTIONS.include?(action.to_s) end
# File lib/action_dispatch/routing/mapper.rb, line 1285 def id_constraint @scope[:constraints][:id] end
# File lib/action_dispatch/routing/mapper.rb, line 1281 def id_constraint? @scope[:constraints] && @scope[:constraints][:id].is_a?(Regexp) end
# File lib/action_dispatch/routing/mapper.rb, line 1320 def name_for_action(as, action) prefix = prefix_name_for_action(as, action) prefix = Mapper.normalize_name(prefix) if prefix name_prefix = @scope[:as] if parent_resource return nil if as.nil? && action.nil? collection_name = parent_resource.collection_name member_name = parent_resource.member_name end name = case @scope[:scope_level] when :nested [name_prefix, prefix] when :collection [prefix, name_prefix, collection_name] when :new [prefix, :new, name_prefix, member_name] when :member [prefix, shallow_scoping? ? @scope[:shallow_prefix] : name_prefix, member_name] when :root [name_prefix, collection_name, prefix] else [name_prefix, member_name, prefix] end candidate = name.select(&:present?).join("_").presence candidate unless as.nil? && @set.routes.find { |r| r.name == candidate } end
# File lib/action_dispatch/routing/mapper.rb, line 1274 def nested_options {}.tap do |options| options[:as] = parent_resource.member_name options[:constraints] = { "#{parent_resource.singular}_id".to_sym => id_constraint } if id_constraint? end end
# File lib/action_dispatch/routing/mapper.rb, line 1297 def path_for_action(action, path) prefix = shallow_scoping? ? "#{@scope[:shallow_path]}/#{parent_resource.path}/:id" : @scope[:path] path = if canonical_action?(action, path.blank?) prefix.to_s else "#{prefix}/#{action_path(action, path)}" end end
# File lib/action_dispatch/routing/mapper.rb, line 1312 def prefix_name_for_action(as, action) if as as.to_s elsif !canonical_action?(action, @scope[:scope_level]) action.to_s end end
# File lib/action_dispatch/routing/mapper.rb, line 1240 def resource_method_scope? [:collection, :member, :new].include?(@scope[:scope_level]) end
# File lib/action_dispatch/routing/mapper.rb, line 1266 def resource_scope(resource) with_scope_level(resource.is_a?(SingletonResource) ? :resource : :resources, resource) do scope(parent_resource.resource_scope) do yield end end end
# File lib/action_dispatch/routing/mapper.rb, line 1236 def resource_scope? [:resource, :resources].include?(@scope[:scope_level]) end
# File lib/action_dispatch/routing/mapper.rb, line 1232 def scope_action_options @scope[:options].slice(:only, :except) end
# File lib/action_dispatch/routing/mapper.rb, line 1228 def scope_action_options? @scope[:options].is_a?(Hash) && (@scope[:options][:only] || @scope[:options][:except]) end
# File lib/action_dispatch/routing/mapper.rb, line 1293 def shallow_scoping? shallow? && @scope[:scope_level] == :member end
# File lib/action_dispatch/routing/mapper.rb, line 1244 def with_exclusive_scope begin old_name_prefix, old_path = @scope[:as], @scope[:path] @scope[:as], @scope[:path] = nil, nil with_scope_level(:exclusive) do yield end ensure @scope[:as], @scope[:path] = old_name_prefix, old_path end end
# File lib/action_dispatch/routing/mapper.rb, line 1257 def with_scope_level(kind, resource = parent_resource) old, @scope[:scope_level] = @scope[:scope_level], kind old_resource, @scope[:scope_level_resource] = @scope[:scope_level_resource], resource yield ensure @scope[:scope_level] = old @scope[:scope_level_resource] = old_resource end