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

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.

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

#add_route(action, options) ⇒ Object

:nodoc:



1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1299

def add_route(action, options) # :nodoc:
  path = path_for_action(action, options.delete(:path))
  action = action.to_s.dup

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

  if !options.fetch(:as, true)
    options.delete(:as)
  else
    options[:as] = name_for_action(options[:as], action)
  end

  mapping = Mapping.new(@set, @scope, path, options)
  app, conditions, requirements, defaults, as, anchor = mapping.to_route
  @set.add_route(app, conditions, requirements, defaults, as, anchor)
end

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



1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1161

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

#decomposed_match(path, options) ⇒ Object

:nodoc:



1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1284

def decomposed_match(path, options) # :nodoc:
  if on = options.delete(:on)
    send(on) { decomposed_match(path, options) }
  else
    case @scope[:scope_level]
    when :resources
      nested { decomposed_match(path, options) }
    when :resource
      member { decomposed_match(path, options) }
    else
      add_route(path, options)
    end
  end
end

#match(path, *rest) ⇒ Object 



1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1249

def match(path, *rest)
  if rest.empty? && Hash === path
    options  = path
    path, to = options.find { |name, value| name.is_a?(String) }
    options[:to] = to
    options.delete(path)
    paths = [path]
  else
    options = rest.pop || {}
    paths = [path] + rest
  end

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

  path_without_format = path.to_s.sub(/\(\.:format\)$/, '')
  if using_match_shorthand?(path_without_format, options)
    options[:to] ||= path_without_format.gsub(%r{^/}, "").sub(%r{/([^/]*)$}, '#\1')
  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

  paths.each { |_path| decomposed_match(_path, options.dup) }
  self
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.



1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1184

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



1231
1232
1233
1234
1235
1236
1237
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1231

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

#nested ⇒ Object 



1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1208

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 



1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1196

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

Options

Takes same options as resources.



981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
 
# File 'lib/action_dispatch/routing/mapper.rb', line 981

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?

    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
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/: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
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          PUT    /sekret/comments/:id(.:format)
comment          DELETE /sekret/comments/:id(.:format)

Examples

# routes call <tt>Admin::PostsController</tt>
resources :posts, :module => "admin"

# resource actions are at /admin/posts.
resources :posts, :path => "admin/posts"



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

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?

    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 



956
957
958
 
# File 'lib/action_dispatch/routing/mapper.rb', line 956

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

#root(options = {}) ⇒ Object 



1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1320

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 



1239
1240
1241
1242
1243
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1239

def shallow
  scope(:shallow => true, :shallow_path => @scope[:path]) do
    yield
  end
end

#shallow? ⇒ Boolean

Returns:

  • (Boolean) 


1245
1246
1247
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1245

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

#using_match_shorthand?(path, options) ⇒ Boolean

Returns:

  • (Boolean) 


1280
1281
1282
 
# File 'lib/action_dispatch/routing/mapper.rb', line 1280

def using_match_shorthand?(path, options)
  path && (options[:to] || options[:action]).nil? && path =~ %r{/[\w/]+$}
end