123456789_123456789_123456789_123456789_123456789_

Module: ActionDispatch::Routing::Mapper::Resources

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In:
::ActionDispatch::Routing::Mapper
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 :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.

Constant Summary

Instance Attribute Summary

Instance Method Summary

Instance Attribute Details

#api_only? ⇒ Boolean (readonly, private)

[ GitHub ] 

  


# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1880



def api_only? # :doc:
  @set.api_only?
end


  








  

    #shallow   (readonly)
  

  [ GitHub ]


  

  


# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1600



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 1607



def shallow?
  !parent_resource.singleton? && @scope[:shallow]
end


  







Instance Method Details



  

    #collection  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'actionpack/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


  








  

    #draw(name)  
  

  [ GitHub ]


  

  


# File 'actionpack/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


  








  

    #match(path, *rest, &block)  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'actionpack/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


  








  

    #member  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'actionpack/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


  








  

    #namespace(path, options = {})  
  



  

    

See Scoping#namespace.


  



  [ GitHub ]


  

  


# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1592



def namespace(path, options = {})
  if resource_scope?
    nested { super }
  else
    super
  end
end


  








  

    #nested  
  

  [ GitHub ]


  

  


# File 'actionpack/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


  








  

    #new  
  

  [ GitHub ]


  

  


# File 'actionpack/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


  








  

    #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 :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


  



  [ GitHub ]


  

  


# File 'actionpack/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


  








  

    #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 :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 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"


  



  [ GitHub ]


  

  


# File 'actionpack/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


  








  

    #resources_path_names(options)  
  

  [ GitHub ]


  

  


# File 'actionpack/lib/action_dispatch/routing/mapper.rb', line 1287



def resources_path_names(options)
  @scope[:path_names].merge!(options)
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.


  



  [ GitHub ]


  

  


# File 'actionpack/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


  








  

    #set_member_mappings_for_resource   (private)
  

  [ GitHub ]


  

  


# File 'actionpack/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


  








  

    #with_scope_level(kind)   (private)
  

  [ GitHub ]


  

  


# File 'actionpack/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