module ActionDispatch::Routing::Mapper::Resources
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: /[^\/]+/
This allows any character other than a slash as part of your :id
.
Constants
- CANONICAL_ACTIONS
- RESOURCE_OPTIONS
- VALID_ON_OPTIONS
CANONICAL_ACTIONS
holds all actions that does not need a prefix or a path appended since they fit properly in their scope level.
Public Instance Methods
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 1520 def collection unless resource_scope? raise ArgumentError, "can't use collection outside resource(s) scope" end with_scope_level(:collection) do path_scope(parent_resource.collection_scope) do yield end end end
# File lib/action_dispatch/routing/mapper.rb, line 1611 def draw(name) path = @draw_paths.find do |_path| File.exist? "#{_path}/#{name}.rb" end unless path msg = "Your router tried to #draw the external file #{name}.rb,\n" \ "but the file was not found in:\n\n" msg += @draw_paths.map { |_path| " * #{_path}" }.join("\n") raise ArgumentError, msg end route_path = "#{path}/#{name}.rb" instance_eval(File.read(route_path), route_path.to_s) end
Matches a URL pattern to one or more routes. For more information, see match.
match 'path' => 'controller#action', via: :patch match 'path', to: 'controller#action', via: :post match 'path', 'otherpath', on: :member, via: :get
# File lib/action_dispatch/routing/mapper.rb, line 1633 def match(path, *rest, &block) if rest.empty? && Hash === path options = path path, to = options.find { |name, _value| name.is_a?(String) } raise ArgumentError, "Route path not specified" if path.nil? case to when Symbol options[:action] = to when String if /#/.match?(to) options[:to] = to else options[:controller] = to end else options[:to] = to end options.delete(path) paths = [path] else options = rest.pop || {} paths = [path] + rest end if options.key?(:defaults) defaults(options.delete(:defaults)) { map_match(paths, options, &block) } else map_match(paths, options, &block) end 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 1543 def member unless resource_scope? raise ArgumentError, "can't use member outside resource(s) scope" end with_scope_level(:member) do if shallow? shallow_scope { path_scope(parent_resource.member_scope) { yield } } else path_scope(parent_resource.member_scope) { yield } end end end
See ActionDispatch::Routing::Mapper::Scoping#namespace
.
# File lib/action_dispatch/routing/mapper.rb, line 1592 def namespace(path, options = {}) if resource_scope? nested { super } else super end end
# File lib/action_dispatch/routing/mapper.rb, line 1571 def nested unless resource_scope? raise ArgumentError, "can't use nested outside resource(s) scope" end with_scope_level(:nested) do if shallow? && shallow_nesting_depth >= 1 shallow_scope do path_scope(parent_resource.nested_scope) do scope(nested_options) { yield } end end else path_scope(parent_resource.nested_scope) do scope(nested_options) { yield } end end end end
# File lib/action_dispatch/routing/mapper.rb, line 1559 def new unless resource_scope? raise ArgumentError, "can't use new outside resource(s) scope" end with_scope_level(:new) do path_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 :profile
This creates six different routes in your application, all mapping to the Profiles
controller (note that the controller is named after the plural):
GET /profile/new GET /profile GET /profile/edit PATCH/PUT /profile DELETE /profile POST /profile
Options¶ ↑
Takes same options as resources
# File lib/action_dispatch/routing/mapper.rb, line 1312 def resource(*resources, &block) options = resources.extract_options!.dup if apply_common_behavior_for(:resource, resources, options, &block) return self end with_scope_level(:resource) do options = apply_action_options options resource_scope(SingletonResource.new(resources.pop, api_only?, @scope[:shallow], options)) do yield if block_given? concerns(options[:concerns]) if options[:concerns] new do get :new end if parent_resource.actions.include?(:new) set_member_mappings_for_resource collection do post :create end if parent_resource.actions.include?(:create) 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 GET /photos/new POST /photos GET /photos/:id GET /photos/:id/edit PATCH/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/:photo_id/comments GET /photos/:photo_id/comments/new POST /photos/:photo_id/comments GET /photos/:photo_id/comments/:id GET /photos/:photo_id/comments/:id/edit PATCH/PUT /photos/:photo_id/comments/:id DELETE /photos/:photo_id/comments/:id
Options¶ ↑
Takes same options as match as well as:
- :path_names
-
Allows you to change the segment component of the
edit
andnew
actions. Actions not specified are not changed.resources :posts, path_names: { new: "brand_new" }
The above example will now change /posts/new to /posts/brand_new.
- :path
-
Allows you to change the path prefix for the resource.
resources :posts, path: 'postings'
The resource and all segments will now route to /postings instead of /posts.
- :only
-
Only generate routes for the given actions.
resources :cows, only: :show resources :cows, only: [:show, :index]
- :except
-
Generate all routes except for the given actions.
resources :cows, except: :show resources :cows, except: [:show, :index]
- :shallow
-
Generates shallow routes for nested resource(s). When placed on a parent resource, generates shallow routes for all nested resources.
resources :posts, shallow: true do resources :comments end
Is the same as:
resources :posts do resources :comments, except: [:show, :edit, :update, :destroy] end resources :comments, only: [:show, :edit, :update, :destroy]
This allows URLs for resources that otherwise would be deeply nested such as a comment on a blog post like
/posts/a-long-permalink/comments/1234
to be shortened to just/comments/1234
.Set
shallow: false
on a child resource to ignore a parent's shallow parameter. - :shallow_path
-
Prefixes nested shallow routes with the specified path.
scope shallow_path: "sekret" do resources :posts do resources :comments, shallow: true end end
The
comments
resource here will have the following routes generated for it:post_comments GET /posts/:post_id/comments(.:format) post_comments POST /posts/:post_id/comments(.:format) new_post_comment GET /posts/:post_id/comments/new(.:format) edit_comment GET /sekret/comments/:id/edit(.:format) comment GET /sekret/comments/:id(.:format) comment PATCH/PUT /sekret/comments/:id(.:format) comment DELETE /sekret/comments/:id(.:format)
- :shallow_prefix
-
Prefixes nested shallow route names with specified prefix.
scope shallow_prefix: "sekret" do resources :posts do resources :comments, shallow: true end end
The
comments
resource here will have the following routes generated for it:post_comments GET /posts/:post_id/comments(.:format) post_comments POST /posts/:post_id/comments(.:format) new_post_comment GET /posts/:post_id/comments/new(.:format) edit_sekret_comment GET /comments/:id/edit(.:format) sekret_comment GET /comments/:id(.:format) sekret_comment PATCH/PUT /comments/:id(.:format) sekret_comment DELETE /comments/:id(.:format)
- :format
-
Allows you to specify the default value for optional
format
segment or disable it by supplyingfalse
. - :param
-
Allows you to override the default param name of
:id
in the URL.
Examples¶ ↑
# routes call <tt>Admin::PostsController</tt> resources :posts, module: "admin" # resource actions are at /admin/posts. resources :posts, path: "admin/posts"
# File lib/action_dispatch/routing/mapper.rb, line 1478 def resources(*resources, &block) options = resources.extract_options!.dup if apply_common_behavior_for(:resources, resources, options, &block) return self end with_scope_level(:resources) do options = apply_action_options options resource_scope(Resource.new(resources.pop, api_only?, @scope[:shallow], options)) do yield if block_given? concerns(options[:concerns]) if options[:concerns] 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) set_member_mappings_for_resource end end self end
# File lib/action_dispatch/routing/mapper.rb, line 1287 def resources_path_names(options) @scope[:path_names].merge!(options) end
You can specify what Rails should route “/” to with the root method:
root to: 'pages#main'
For options, see match
, as root
uses it internally.
You can also pass a string which will expand
root 'pages#main'
You should put the root route at the top of config/routes.rb
, because this means it will be matched first. As this is the most popular route of most Rails applications, this is beneficial.
# File lib/action_dispatch/routing/mapper.rb, line 1680 def root(path, options = {}) if path.is_a?(String) options[:to] = path elsif path.is_a?(Hash) && options.empty? options = path else raise ArgumentError, "must be called with a path and/or options" end if @scope.resources? with_scope_level(:root) do path_scope(parent_resource.path) do match_root_route(options) end end else match_root_route(options) end end
# File lib/action_dispatch/routing/mapper.rb, line 1600 def shallow @scope = @scope.new(shallow: true) yield ensure @scope = @scope.parent end
# File lib/action_dispatch/routing/mapper.rb, line 1607 def shallow? !parent_resource.singleton? && @scope[:shallow] end
Private Instance Methods
# File lib/action_dispatch/routing/mapper.rb, line 1744 def action_options?(options) options[:only] || options[:except] end
# File lib/action_dispatch/routing/mapper.rb, line 1826 def action_path(name) @scope[:path_names][name.to_sym] || name end
# File lib/action_dispatch/routing/mapper.rb, line 1962 def add_route(action, controller, options, _path, to, via, formatted, anchor, options_constraints) path = path_for_action(action, _path) raise ArgumentError, "path is required" if path.blank? action = action.to_s default_action = options.delete(:action) || @scope[:action] if /^[\w\-\/]+$/.match?(action) default_action ||= action.tr("-", "_") unless action.include?("/") else action = nil end as = if !options.fetch(:as, true) # if it's set to nil or false options.delete(:as) else name_for_action(options.delete(:as), action) end path = Mapping.normalize_path URI::DEFAULT_PARSER.escape(path), formatted ast = Journey::Parser.parse path mapping = Mapping.build(@scope, @set, ast, controller, default_action, to, via, formatted, options_constraints, anchor, options) @set.add_route(mapping, as) end
# File lib/action_dispatch/routing/mapper.rb, line 1880 def api_only? # :doc: @set.api_only? end
# File lib/action_dispatch/routing/mapper.rb, line 1739 def apply_action_options(options) return options if action_options? options options.merge scope_action_options end
# File lib/action_dispatch/routing/mapper.rb, line 1705 def apply_common_behavior_for(method, resources, options, &block) if resources.length > 1 resources.each { |r| public_send(method, r, options, &block) } return true end if options[:shallow] options.delete(:shallow) shallow do public_send(method, resources.pop, options, &block) end return true end if resource_scope? nested { public_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 public_send(method, resources.pop, options, &block) end return true end false end
# File lib/action_dispatch/routing/mapper.rb, line 1802 def canonical_action?(action) resource_method_scope? && CANONICAL_ACTIONS.include?(action.to_s) end
# File lib/action_dispatch/routing/mapper.rb, line 1947 def decomposed_match(path, controller, options, _path, to, via, formatted, anchor, options_constraints) if on = options.delete(:on) send(on) { decomposed_match(path, controller, options, _path, to, via, formatted, anchor, options_constraints) } else case @scope.scope_level when :resources nested { decomposed_match(path, controller, options, _path, to, via, formatted, anchor, options_constraints) } when :resource member { decomposed_match(path, controller, options, _path, to, via, formatted, anchor, options_constraints) } else add_route(path, controller, options, _path, to, via, formatted, anchor, options_constraints) end end end
# File lib/action_dispatch/routing/mapper.rb, line 1932 def get_to_from_path(path, to, action) return to if to || action path_without_format = path.sub(/\(\.:format\)$/, "") if using_match_shorthand?(path_without_format) path_without_format.delete_prefix("/").sub(%r{/([^/]*)$}, '#\1').tr("-", "_") else nil end end
# File lib/action_dispatch/routing/mapper.rb, line 1891 def map_match(paths, options) if options[:on] && !VALID_ON_OPTIONS.include?(options[:on]) raise ArgumentError, "Unknown scope #{on.inspect} given to :on" end if @scope[:to] options[:to] ||= @scope[:to] end if @scope[:controller] && @scope[:action] options[:to] ||= "#{@scope[:controller]}##{@scope[:action]}" end controller = options.delete(:controller) || @scope[:controller] option_path = options.delete :path to = options.delete :to via = Mapping.check_via Array(options.delete(:via) { @scope[:via] }) formatted = options.delete(:format) { @scope[:format] } anchor = options.delete(:anchor) { true } options_constraints = options.delete(:constraints) || {} path_types = paths.group_by(&:class) (path_types[String] || []).each do |_path| route_options = options.dup if _path && option_path raise ArgumentError, "Ambiguous route definition. Both :path and the route path were specified as strings." end to = get_to_from_path(_path, to, route_options[:action]) decomposed_match(_path, controller, route_options, _path, to, via, formatted, anchor, options_constraints) end (path_types[Symbol] || []).each do |action| route_options = options.dup decomposed_match(action, controller, route_options, option_path, to, via, formatted, anchor, options_constraints) end self end
# File lib/action_dispatch/routing/mapper.rb, line 1989 def match_root_route(options) args = ["/", { as: :root, via: :get }.merge(options)] match(*args) end
# File lib/action_dispatch/routing/mapper.rb, line 1842 def name_for_action(as, action) prefix = prefix_name_for_action(as, action) name_prefix = @scope[:as] if parent_resource return nil unless as || action collection_name = parent_resource.collection_name member_name = parent_resource.member_name end action_name = @scope.action_name(name_prefix, prefix, collection_name, member_name) candidate = action_name.select(&:present?).join("_") unless candidate.empty? # If a name was not explicitly given, we check if it is valid # and return nil in case it isn't. Otherwise, we pass the invalid name # forward so the underlying router engine treats it and raises an exception. if as.nil? candidate unless !candidate.match?(/\A[_a-z]/i) || has_named_route?(candidate) else candidate end end end
# File lib/action_dispatch/routing/mapper.rb, line 1779 def nested_options options = { as: parent_resource.member_name } options[:constraints] = { parent_resource.nested_param => param_constraint } if param_constraint? options end
# File lib/action_dispatch/routing/mapper.rb, line 1760 def nested_scope? @scope.nested? end
# File lib/action_dispatch/routing/mapper.rb, line 1798 def param_constraint @scope[:constraints][parent_resource.param] end
# File lib/action_dispatch/routing/mapper.rb, line 1794 def param_constraint? @scope[:constraints] && @scope[:constraints][parent_resource.param].is_a?(Regexp) end
# File lib/action_dispatch/routing/mapper.rb, line 1701 def parent_resource @scope[:scope_level_resource] end
# File lib/action_dispatch/routing/mapper.rb, line 1816 def path_for_action(action, path) return "#{@scope[:path]}/#{path}" if path if canonical_action?(action) @scope[:path].to_s else "#{@scope[:path]}/#{action_path(action)}" end end
# File lib/action_dispatch/routing/mapper.rb, line 1884 def path_scope(path) @scope = @scope.new(path: merge_path_scope(@scope[:path], path)) yield ensure @scope = @scope.parent end
# File lib/action_dispatch/routing/mapper.rb, line 1830 def prefix_name_for_action(as, action) if as prefix = as elsif !canonical_action?(action) prefix = action end if prefix && prefix != "/" && !prefix.empty? Mapper.normalize_name prefix.to_s.tr("-", "_") end end
# File lib/action_dispatch/routing/mapper.rb, line 1756 def resource_method_scope? @scope.resource_method_scope? end
# File lib/action_dispatch/routing/mapper.rb, line 1771 def resource_scope(resource) @scope = @scope.new(scope_level_resource: resource) controller(resource.resource_scope) { yield } ensure @scope = @scope.parent end
# File lib/action_dispatch/routing/mapper.rb, line 1752 def resource_scope? @scope.resource_scope? end
# File lib/action_dispatch/routing/mapper.rb, line 1748 def scope_action_options @scope[:action_options] || {} end
# File lib/action_dispatch/routing/mapper.rb, line 1868 def set_member_mappings_for_resource # :doc: member do get :edit if parent_resource.actions.include?(:edit) get :show if parent_resource.actions.include?(:show) if parent_resource.actions.include?(:update) patch :update put :update end delete :destroy if parent_resource.actions.include?(:destroy) end end
# File lib/action_dispatch/routing/mapper.rb, line 1788 def shallow_nesting_depth @scope.find_all { |node| node.frame[:scope_level_resource] }.count { |node| node.frame[:scope_level_resource].shallow? } end
# File lib/action_dispatch/routing/mapper.rb, line 1806 def shallow_scope scope = { as: @scope[:shallow_prefix], path: @scope[:shallow_path] } @scope = @scope.new scope yield ensure @scope = @scope.parent end
# File lib/action_dispatch/routing/mapper.rb, line 1943 def using_match_shorthand?(path) %r{^/?[-\w]+/[-\w/]+$}.match?(path) end
# File lib/action_dispatch/routing/mapper.rb, line 1764 def with_scope_level(kind) # :doc: @scope = @scope.new_level(kind) yield ensure @scope = @scope.parent end