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, :param, :concerns]
- CANONICAL_ACTIONS =
%w(index create new show update destroy)
- RESOURCE_METHOD_SCOPES =
[:collection, :member, :new]
- RESOURCE_SCOPES =
[:resource, :resources]
Instance Method Summary collapse
-
#add_route(action, options) ⇒ Object
:nodoc:.
-
#collection ⇒ Object
To add a route to the collection:.
-
#decomposed_match(path, options) ⇒ Object
:nodoc:.
-
#match(path, *rest) ⇒ Object
match ‘path’ => ‘controller#action’ match ‘path’, to: ‘controller#action’ match ‘path’, ‘otherpath’, on: :member, via: :get.
-
#member ⇒ Object
To add a member route, add a member block into the resource block:.
-
#namespace(path, options = {}) ⇒ Object
See ActionDispatch::Routing::Mapper::Scoping#namespace.
- #nested ⇒ Object
- #new ⇒ Object
-
#resource(*resources, &block) ⇒ Object
Sometimes, you have a resource that clients always look up without referencing an ID.
-
#resources(*resources, &block) ⇒ Object
In Rails, a resourceful route provides a mapping between HTTP verbs and URLs and controller actions.
- #resources_path_names(options) ⇒ Object
- #root(path, options = {}) ⇒ Object
- #shallow ⇒ Object
- #shallow? ⇒ Boolean
- #using_match_shorthand?(path, options) ⇒ Boolean
Instance Method Details
#add_route(action, options) ⇒ Object
:nodoc:
1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 |
# File 'lib/action_dispatch/routing/mapper.rb', line 1422 def add_route(action, ) # :nodoc: path = path_for_action(action, .delete(:path)) action = action.to_s.dup if action =~ /^[\w\/]+$/ [:action] ||= action unless action.include?("/") else action = nil end if !.fetch(:as, true) .delete(:as) else [:as] = name_for_action([:as], action) end mapping = Mapping.new(@set, @scope, URI.parser.escape(path), ) 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.
1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 |
# File 'lib/action_dispatch/routing/mapper.rb', line 1276 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:
1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 |
# File 'lib/action_dispatch/routing/mapper.rb', line 1407 def decomposed_match(path, ) # :nodoc: if on = .delete(:on) send(on) { decomposed_match(path, ) } else case @scope[:scope_level] when :resources nested { decomposed_match(path, ) } when :resource member { decomposed_match(path, ) } else add_route(path, ) end end end |
#match(path, *rest) ⇒ Object
match ‘path’ => ‘controller#action’ match ‘path’, to: ‘controller#action’ match ‘path’, ‘otherpath’, on: :member, via: :get
1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 |
# File 'lib/action_dispatch/routing/mapper.rb', line 1367 def match(path, *rest) if rest.empty? && Hash === path = path path, to = .find { |name, _value| name.is_a?(String) } [:to] = to .delete(path) paths = [path] else = rest.pop || {} paths = [path] + rest end [:anchor] = true unless .key?(:anchor) if [:on] && !VALID_ON_OPTIONS.include?([:on]) raise ArgumentError, "Unknown scope #{on.inspect} given to :on" end if @scope[:controller] && @scope[:action] [:to] ||= "#{@scope[:controller]}##{@scope[:action]}" end paths.each do |_path| = .dup [:path] ||= _path if _path.is_a?(String) path_without_format = _path.to_s.sub(/\(\.:format\)$/, '') if using_match_shorthand?(path_without_format, ) [:to] ||= path_without_format.gsub(%r{^/}, "").sub(%r{/([^/]*)$}, '#\1') end decomposed_match(_path, ) end 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.
1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 |
# File 'lib/action_dispatch/routing/mapper.rb', line 1299 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
1346 1347 1348 1349 1350 1351 1352 |
# File 'lib/action_dispatch/routing/mapper.rb', line 1346 def namespace(path, = {}) if resource_scope? nested { super } else super end end |
#nested ⇒ Object
1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 |
# File 'lib/action_dispatch/routing/mapper.rb', line 1323 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, ) { yield } else scope(@scope[:shallow_path], :as => @scope[:shallow_prefix]) do scope(parent_resource.nested_scope, ) { yield } end end end else scope(parent_resource.nested_scope, ) { yield } end end end |
#new ⇒ Object
1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 |
# File 'lib/action_dispatch/routing/mapper.rb', line 1311 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
PATCH/PUT /geocoder
DELETE /geocoder
Options
Takes same options as resources
.
1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 |
# File 'lib/action_dispatch/routing/mapper.rb', line 1079 def resource(*resources, &block) = resources..dup if apply_common_behavior_for(:resource, resources, , &block) return self end resource_scope(:resource, SingletonResource.new(resources.pop, )) do yield if block_given? concerns([:concerns]) if [: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, &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
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
andnew
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 supplyingfalse
.
Examples
# routes call <tt>Admin::PostsController</tt>
resources :posts, module: "admin"
# resource actions are at /admin/posts.
resources :posts, path: "admin/posts"
1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 |
# File 'lib/action_dispatch/routing/mapper.rb', line 1237 def resources(*resources, &block) = resources..dup if apply_common_behavior_for(:resources, resources, , &block) return self end resource_scope(:resources, Resource.new(resources.pop, )) 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 self end |
#resources_path_names(options) ⇒ Object
1054 1055 1056 |
# File 'lib/action_dispatch/routing/mapper.rb', line 1054 def resources_path_names() @scope[:path_names].merge!() end |
#root(path, options = {}) ⇒ Object
1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 |
# File 'lib/action_dispatch/routing/mapper.rb', line 1443 def root(path, ={}) if path.is_a?(String) [:to] = path elsif path.is_a?(Hash) and .empty? = path else raise ArgumentError, "must be called with a path and/or options" end if @scope[:scope_level] == :resources with_scope_level(:root) do scope(parent_resource.path) do super() end end else super() end end |
#shallow ⇒ Object
1354 1355 1356 1357 1358 |
# File 'lib/action_dispatch/routing/mapper.rb', line 1354 def shallow scope(:shallow => true, :shallow_path => @scope[:path]) do yield end end |
#shallow? ⇒ Boolean
1360 1361 1362 |
# File 'lib/action_dispatch/routing/mapper.rb', line 1360 def shallow? parent_resource.instance_of?(Resource) && @scope[:shallow] end |
#using_match_shorthand?(path, options) ⇒ Boolean
1403 1404 1405 |
# File 'lib/action_dispatch/routing/mapper.rb', line 1403 def using_match_shorthand?(path, ) path && ([:to] || [:action]).nil? && path =~ %r{/[\w/]+$} end |