Skip to content
Browse files

Updates to nested/shallow routes discussion in "Routing from the Outs…

…ide In" guide.

Added guidance on avoiding deeply-nested routes, further explanation of :shallow, show example of :has_many and :shallow together.
  • Loading branch information...
1 parent 310297e commit 0a9a80b2db4f86588400f1fc85f72eab95a9911a @ffmike ffmike committed Sep 8, 2008
Showing with 20 additions and 1 deletion.
  1. +20 −1 railties/doc/guides/routing/routing_outside_in.txt
View
21 railties/doc/guides/routing/routing_outside_in.txt
@@ -455,7 +455,9 @@ However, without the use of +name_prefix => nil+, deeply-nested resources quickl
/publishers/1/magazines/2/photos/3
-------------------------------------------------------
-The corresponding route helper would be +publisher_magazine_photo_url+, requiring you to specify objects at all three levels.
+The corresponding route helper would be +publisher_magazine_photo_url+, requiring you to specify objects at all three levels. Indeed, this situation is confusing enough that a popular link:http://weblog.jamisbuck.org/2007/2/5/nesting-resources[article] by Jamis Buck proposes a rule of thumb for good Rails design:
+
+_Resources should never be nested more than 1 level deep._
==== Shallow Nesting
@@ -479,6 +481,23 @@ This will enable recognition of (among others) these routes:
/magazines/2/photos ==> magazines_photos_path(2)
/photos/3 ==> photo_path(3)
-------------------------------------------------------
+
+With shallow nesting, you need only supply enough information to uniquely identify the resource that you want to work with - but you _can_ supply more information. All of the nested routes continue to work, just as they would without shallow nesting, but less-deeply nested routes (even direct routes) work as well. So, with the declaration above, all of these routes refer to the same resource:
+
+-------------------------------------------------------
+/publishers/1/magazines/2/photos/3 ==> publisher_magazine_photo_path(1,2,3)
+/magazines/2/photos/3 ==> magazine_photo_path(2,3)
+/photos/3 ==> photo_path(3)
+-------------------------------------------------------
+
+Shallow nesting gives you the flexibility to use the shorter direct routes when you like, while still preserving the longer nested routes for times when they add code clarity.
+
+If you like, you can combine shallow nesting with the +:has_one+ and +:has_many+ options:
+
+[source, ruby]
+-------------------------------------------------------
+map.resources :publishers, :has_many => { :magazines => :photos }, :shallow => true
+-------------------------------------------------------
=== Adding More RESTful Actions

0 comments on commit 0a9a80b

Please sign in to comment.
Something went wrong with that request. Please try again.