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

Included in:
ActionDispatch::Routing::Mapper
Defined in:
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

Defined Under Namespace

Classes: Resource, SingletonResource

Constant Summary collapse

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.

[:new, :collection, :member]
RESOURCE_OPTIONS = 
[:as, :controller, :path, :only, :except]
CANONICAL_ACTIONS = 
%w(index create new show update destroy)

Instance Method Summary collapse

Instance Method Details

#collection ⇒ Object

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.



1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1033

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

#initialize(*args) ⇒ Object

:nodoc:



880
881
882
883
 
# File 'lib/action_dispatch/routing/mapper.rb', line 880

def initialize(*args) #:nodoc:
  super
  @scope[:path_names] = @set.resources_path_names
end

#match(*args) ⇒ Object 



1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1121

def match(*args)
  options = args.extract_options!.dup
  options[:anchor] = true unless options.key?(:anchor)

  if args.length > 1
    args.each { |path| match(path, options.dup) }
    return self
  end

  on = options.delete(:on)
  if VALID_ON_OPTIONS.include?(on)
    args.push(options)
    return send(on){ match(*args) }
  elsif on
    raise ArgumentError, "Unknown scope #{on.inspect} given to :on"
  end

  if @scope[:scope_level] == :resources
    args.push(options)
    return nested { match(*args) }
  elsif @scope[:scope_level] == :resource
    args.push(options)
    return member { match(*args) }
  end

  action = args.first
  path = path_for_action(action, options.delete(:path))

  if action.to_s =~ /^[\w\/]+$/
    options[:action] ||= action unless action.to_s.include?("/")
  else
    action = nil
  end

  if options.key?(:as) && !options[:as]
    options.delete(:as)
  else
    options[:as] = name_for_action(options[:as], action)
  end

  super(path, options)
end

#member ⇒ Object

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.



1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1056

def member
  unless resource_scope?
    raise ArgumentError, "can't use member outside resource(s) scope"
  end

  with_scope_level(:member) do
    scope(parent_resource.member_scope) do
      yield
    end
  end
end

#namespace(path, options = {}) ⇒ Object

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



1103
1104
1105
1106
1107
1108
1109
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1103

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

#nested ⇒ Object 



1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1080

def nested
  unless resource_scope?
    raise ArgumentError, "can't use nested outside resource(s) scope"
  end

  with_scope_level(:nested) do
    if shallow?
      with_exclusive_scope do
        if @scope[:shallow_path].blank?
          scope(parent_resource.nested_scope, nested_options) { yield }
        else
          scope(@scope[:shallow_path], :as => @scope[:shallow_prefix]) do
            scope(parent_resource.nested_scope, nested_options) { yield }
          end
        end
      end
    else
      scope(parent_resource.nested_scope, nested_options) { yield }
    end
  end
end

#new ⇒ Object 



1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1068

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, &block) ⇒ Object

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

creates six different routes in your application, all mapping to the GeoCoders controller (note that the controller is named after the plural):

GET     /geocoder/new
POST    /geocoder
GET     /geocoder
GET     /geocoder/edit
PUT     /geocoder
DELETE  /geocoder



907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
 
# File 'lib/action_dispatch/routing/mapper.rb', line 907

def resource(*resources, &block)
  options = resources.extract_options!

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

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

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

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

    member do
      get    :edit if parent_resource.actions.include?(:edit)
      get    :show if parent_resource.actions.include?(:show)
      put    :update if parent_resource.actions.include?(:update)
      delete :destroy if parent_resource.actions.include?(:destroy)
    end
  end

  self
end

#resources(*resources, &block) ⇒ Object

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/new
POST    /photos
GET     /photos/:id
GET     /photos/:id/edit
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/:id/comments/new
POST    /photos/:id/comments
GET     /photos/:id/comments/:id
GET     /photos/:id/comments/:id/edit
PUT     /photos/:id/comments/:id
DELETE  /photos/:id/comments/:id

Supported options

:path_names

Allows you to change the paths of the seven default actions. Paths not specified are not changed.

resources :posts, :path_names => { :new => "brand_new" }

The above example will now change /posts/new to /posts/brand_new

:module

Set the module where the controller can be found. Defaults to nothing.

resources :posts, :module => "admin"

All requests to the posts resources will now go to Admin::PostsController.

:path

Set a path prefix for this resource.

resources :posts, :path => "admin"

All actions for this resource will now be at /admin/posts.



991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
 
# File 'lib/action_dispatch/routing/mapper.rb', line 991

def resources(*resources, &block)
  options = resources.extract_options!

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

  resource_scope(Resource.new(resources.pop, options)) do
    yield if block_given?

    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)

    member do
      get    :edit if parent_resource.actions.include?(:edit)
      get    :show if parent_resource.actions.include?(:show)
      put    :update if parent_resource.actions.include?(:update)
      delete :destroy if parent_resource.actions.include?(:destroy)
    end
  end

  self
end

#resources_path_names(options) ⇒ Object 



885
886
887
 
# File 'lib/action_dispatch/routing/mapper.rb', line 885

def resources_path_names(options)
  @scope[:path_names].merge!(options)
end

#root(options = {}) ⇒ Object 



1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1164

def root(options={})
  if @scope[:scope_level] == :resources
    with_scope_level(:root) do
      scope(parent_resource.path) do
        super(options)
      end
    end
  else
    super(options)
  end
end

#shallow ⇒ Object 



1111
1112
1113
1114
1115
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1111

def shallow
  scope(:shallow => true) do
    yield
  end
end

#shallow? ⇒ Boolean

Returns:

  • (Boolean) 


1117
1118
1119
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1117

def shallow?
  parent_resource.instance_of?(Resource) && @scope[:shallow]
end