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
holds all actions that does not need a prefix or a path appended since they fit properly in their scope level.
[:new, :collection, :member]
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.
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1553
def collection(&block)
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, &block)
end
end
Loads another routes file with the given name
located inside the config/routes
directory. In that file, you can use the normal routing DSL, but do not surround it with a Rails.application.routes.draw
block.
# config/routes.rb
Rails.application.routes.draw do
draw :admin # Loads `config/routes/admin.rb`
draw "third_party/some_gem" # Loads `config/routes/third_party/some_gem.rb`
end
# config/routes/admin.rb
namespace :admin do
resources :accounts
end
# config/routes/third_party/some_gem.rb
mount SomeGem::Engine, at: "/some_gem"
CAUTION: Use this feature with care. Having multiple routes files can negatively impact discoverability and readability. For most applications —even those with a few hundred routes — it’s easier for developers to have a single routes file.
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1662
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', to: 'controller#action', via: :post
match 'path', 'otherpath', on: :member, via: :get
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1683
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 to.include?("#")
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.
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1574
def member(&block)
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, &block)
}
else
path_scope(parent_resource.member_scope, &block)
end
end
end
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1621
def namespace(path, options = {})
if resource_scope?
nested { super }
else
super
end
end
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1600
def nested(&block)
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, &block)
end
end
else
path_scope(parent_resource.nested_scope) do
scope(nested_options, &block)
end
end
end
end
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1590
def new(&block)
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)), &block)
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
If you want instances of a model to work with this resource via record identification (e.g. in form_with
or redirect_to
), you will need to call resolve
:
resource :profile
resolve('Profile') { [:profile] }
# Enables this to work with singular routes:
form_with(model: @profile) {}
Options
Takes same options as resources
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1342
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 +Admin::PostsController+
resources :posts, module: "admin"
# resource actions are at /admin/posts.
resources :posts, path: "admin/posts"
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1512
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
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1309
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.
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1730
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
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1629
def shallow
@scope = @scope.new(shallow: true)
yield
ensure
@scope = @scope.parent
end
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1636
def shallow?
!parent_resource.singleton? && @scope[:shallow]
end
Private instance methods
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1930
def api_only? # :doc:
@set.api_only?
end
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1918
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
Source code GitHub
# File actionpack/lib/action_dispatch/routing/mapper.rb, line 1814
def with_scope_level(kind) # :doc:
@scope = @scope.new_level(kind)
yield
ensure
@scope = @scope.parent
end