Module: ActionDispatch::Routing::Mapper::Resources
| Relationships & Source Files | |
| Extension / Inclusion / Inheritance Descendants | |
| Included In: | |
| Defined in: | actionpack/lib/action_dispatch/routing/mapper.rb | 
Overview
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 :photosSometimes, 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 :profileIt’s common to have resources that are logically children of other resources:
resources :magazines do
  resources :ads
endYou 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
endBy 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.
Constant Summary
- 
    CANONICAL_ACTIONS =
    
 # File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1174%w(index create new show update destroy)
- 
    RESOURCE_OPTIONS =
    
 # File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1173[:as, :controller, :path, :only, :except, :param, :concerns] 
- 
    VALID_ON_OPTIONS =
    # File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1172CANONICAL_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] 
Instance Attribute Summary
- #shallow readonly
- #shallow? ⇒ Boolean readonly
- #api_only? ⇒ Boolean readonly private
Instance Method Summary
- 
    
      #collection(&block)  
    
    To add a route to the collection: 
- 
    
      #draw(name)  
    
    Loads another routes file with the given namelocated inside theconfig/routesdirectory.
- 
    
      #match(path, *rest, &block)  
    
    Matches a URL pattern to one or more routes. 
- 
    
      #member(&block)  
    
    To add a member route, add a member block into the resource block: 
- 
    
      #namespace(path, options = {})  
    
    See Scoping#namespace. 
- #nested(&block)
- #new(&block)
- 
    
      #resource(*resources, &block)  
    
    Sometimes, you have a resource that clients always look up without referencing an ID. 
- 
    
      #resources(*resources, &block)  
    
    In Rails, a resourceful route provides a mapping between HTTP verbs and URLs and controller actions. 
- #resources_path_names(options)
- 
    
      #root(path, options = {})  
    
    You can specify what ::Railsshould route “/” to with the root method:
- #set_member_mappings_for_resource private
- #with_scope_level(kind) private
Instance Attribute Details
    #api_only?  ⇒ Boolean  (readonly, private)
  
  [ GitHub ]
# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1926
def api_only? # :doc: @set.api_only? end
#shallow (readonly)
[ GitHub ]# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1624
def shallow @scope = @scope.new(shallow: true) yield ensure @scope = @scope.parent end
    #shallow?  ⇒ Boolean  (readonly)
  
  [ GitHub ]
# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1631
def shallow? !parent_resource.singleton? && @scope[:shallow] end
Instance Method Details
#collection(&block)
# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1548
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
#draw(name)
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.
# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1657
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
#match(path, *rest, &block)
Matches a URL pattern to one or more routes. For more information, see [match](Base#match).
match 'path' => 'controller#action', via: :patch
match 'path', to: 'controller#action', via: :post
match 'path', 'otherpath', on: :member, via: :get# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1679
def match(path, *rest, &block) if rest.empty? && Hash === path = path path, to = .find { |name, _value| name.is_a?(String) } raise ArgumentError, "Route path not specified" if path.nil? case to when Symbol [:action] = to when String if to.include?("#") [:to] = to else [:controller] = to end else [:to] = to end .delete(path) paths = [path] else = rest.pop || {} paths = [path] + rest end if .key?(:defaults) defaults(.delete(:defaults)) { map_match(paths, , &block) } else map_match(paths, , &block) end end
#member(&block)
To add a member route, add a member block into the resource block:
resources :photos do
  member do
    get 'preview'
  end
endThis 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 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1569
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
#namespace(path, options = {})
See Scoping#namespace.
# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1616
def namespace(path, = {}) if resource_scope? nested { super } else super end end
#nested(&block)
[ GitHub ]# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1595
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(, &block) end end else path_scope(parent_resource.nested_scope) do scope(, &block) end end end end
#new(&block)
[ GitHub ]# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1585
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
#resource(*resources, &block)
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 :profileThis 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      /profileIf 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
# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1337
def resource(*resources, &block) = resources..dup if apply_common_behavior_for(:resource, resources, , &block) return self end with_scope_level(:resource) do = resource_scope(SingletonResource.new(resources.pop, api_only?, @scope[:shallow], )) do yield if block_given? concerns([:concerns]) if [: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
#resources(*resources, &block)
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 :photoscreates 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/:idResources can also be nested infinitely by using this block syntax:
resources :photos do
  resources :comments
endThis 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/:idOptions
Takes same options as match as well as:
:path_names
:   Allows you to change the segment component of the edit and #new
    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 supplying false.
: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"# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1507
def resources(*resources, &block) = resources..dup if apply_common_behavior_for(:resources, resources, , &block) return self end with_scope_level(:resources) do = resource_scope(Resource.new(resources.pop, api_only?, @scope[:shallow], )) do yield if block_given? concerns([:concerns]) if [: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
#resources_path_names(options)
[ GitHub ]# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1304
def resources_path_names() @scope[:path_names].merge!() end
#root(path, options = {})
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 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1726
def root(path, = {}) if path.is_a?(String) [:to] = path elsif path.is_a?(Hash) && .empty? = 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() end end else match_root_route() end end
#set_member_mappings_for_resource (private)
[ GitHub ]# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1914
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
#with_scope_level(kind) (private)
[ GitHub ]# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1810
def with_scope_level(kind) # :doc: @scope = @scope.new_level(kind) yield ensure @scope = @scope.parent end