module ActionDispatch::Routing::Mapper::Resources - actionpack-4.2.3 Documentation

# 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

collection() { || ... } click to toggle source

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 1387
    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

match(path, *rest) click to toggle source

match 'path' => 'controller#action' match 'path', to: 'controller#action' match 'path', 'otherpath', on: :member, via: :get

    # File lib/action_dispatch/routing/mapper.rb, line 1472
    def match(path, *rest)
      if rest.empty? && Hash === path
        options  = path
        path, to = options.find { |name, _value| name.is_a?(String) }

        case to
        when Symbol
          options[:action] = to
        when String
          if 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

      options[:anchor] = true unless options.key?(:anchor)

      if options[:on] && !VALID_ON_OPTIONS.include?(options[:on])
        raise ArgumentError, "Unknown scope #{on.inspect} given to :on"
      end

      if @scope[:controller] && @scope[:action]
        options[:to] ||= "#{@scope[:controller]}##{@scope[:action]}"
      end

      paths.each do |_path|
        route_options = options.dup
        route_options[:path] ||= _path if _path.is_a?(String)

        path_without_format = _path.to_s.sub(/\(\.:format\)$/, '')
        if using_match_shorthand?(path_without_format, route_options)
          route_options[:to] ||= path_without_format.gsub(%r{^/}, "").sub(%r{/([^/]*)$}, '#\1')
          route_options[:to].tr!("-", "_")
        end

        decomposed_match(_path, route_options)
      end
      self
    end

member() { || ... } click to toggle source

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 1410
    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(parent_resource.member_scope) { yield }
        else
          scope(parent_resource.member_scope) { yield }
        end
      end
    end

namespace(path, options = {}) click to toggle source

See ActionDispatch::Routing::Mapper::Scoping#namespace

Calls superclass method

    # File lib/action_dispatch/routing/mapper.rb, line 1451
    def namespace(path, options = {})
      if resource_scope?
        nested { super }
      else
        super
      end
    end

nested() { || ... } click to toggle source

    # File lib/action_dispatch/routing/mapper.rb, line 1436
    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(parent_resource.nested_scope, nested_options) { yield }
        else
          scope(parent_resource.nested_scope, nested_options) { yield }
        end
      end
    end

new() { || ... } click to toggle source

    # File lib/action_dispatch/routing/mapper.rb, line 1424
    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

resource(*resources) { || ... } click to toggle source

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

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
    POST      /profile
    GET       /profile
    GET       /profile/edit
    PATCH/PUT /profile
    DELETE    /profile

### Options¶ ↑

Takes same options as `resources`.

    # File lib/action_dispatch/routing/mapper.rb, line 1190
    def resource(*resources, &block)
      options = resources.extract_options!.dup

      if apply_common_behavior_for(:resource, resources, options, &block)
        return self
      end

      resource_scope(:resource, SingletonResource.new(resources.pop, options)) do
        yield if block_given?

        concerns(options[:concerns]) if options[:concerns]

        collection do
          post :create
        end if parent_resource.actions.include?(:create)

        new do
          get :new
        end if parent_resource.actions.include?(:new)

        set_member_mappings_for_resource
      end

      self
    end

resources(*resources) { || ... } click to toggle source

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 `Base#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`.

: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`.

### 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 1348
    def resources(*resources, &block)
      options = resources.extract_options!.dup

      if apply_common_behavior_for(:resources, resources, options, &block)
        return self
      end

      resource_scope(:resources, Resource.new(resources.pop, 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

      self
    end

resources_path_names(options) click to toggle source

    # File lib/action_dispatch/routing/mapper.rb, line 1165
    def resources_path_names(options)
      @scope[:path_names].merge!(options)
    end

root(path, options={}) click to toggle source
Calls superclass method

    # File lib/action_dispatch/routing/mapper.rb, line 1564
    def root(path, options={})
      if path.is_a?(String)
        options[:to] = path
      elsif path.is_a?(Hash) and 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
          scope(parent_resource.path) do
            super(options)
          end
        end
      else
        super(options)
      end
    end

shallow() { || ... } click to toggle source

    # File lib/action_dispatch/routing/mapper.rb, line 1459
    def shallow
      scope(:shallow => true) do
        yield
      end
    end

shallow?() click to toggle source

    # File lib/action_dispatch/routing/mapper.rb, line 1465
    def shallow?
      parent_resource.instance_of?(Resource) && @scope[:shallow]
    end

using_match_shorthand?(path, options) click to toggle source

    # File lib/action_dispatch/routing/mapper.rb, line 1522
    def using_match_shorthand?(path, options)
      path && (options[:to] || options[:action]).nil? && path =~ %r{^/?[-\w]+/[-\w/]+$}
    end

### Protected Instance Methods

set_member_mappings_for_resource() click to toggle source

    # File lib/action_dispatch/routing/mapper.rb, line 1772
    def set_member_mappings_for_resource
      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_exclusive_scope() { || ... } click to toggle source

    # File lib/action_dispatch/routing/mapper.rb, line 1651
    def with_exclusive_scope
      begin
        @scope = @scope.new(:as => nil, :path => nil)

        with_scope_level(:exclusive) do
          yield
        end
      ensure
        @scope = @scope.parent
      end
    end

with_scope_level(kind) { || ... } click to toggle source

    # File lib/action_dispatch/routing/mapper.rb, line 1663
    def with_scope_level(kind)
      @scope = @scope.new_level(kind)
      yield
    ensure
      @scope = @scope.parent
    end