Added section on controller namespaces.

1 files changed, 14 insertions, 0 deletions

diff --git a/railties/doc/guides/routing/routing_outside_in.txt b/railties/doc/guides/routing/routing_outside_in.txt
index 29b69ab47d..065adff535 100644
--- a/railties/doc/guides/routing/routing_outside_in.txt
+++ b/railties/doc/guides/routing/routing_outside_in.txt
@@ -258,6 +258,19 @@ DELETE     /photos/1       Images      destroy  delete a specific image
 
 NOTE: The helpers will be generated with the name of the resource, not the name of the controller. So in this case, you'd still get +photos_path+, +photos_new_path+, and so on.
 
+=== Controller Namespaces and Routing ===
+
+Rails allows you to group your controllers into namespaces by saving them in folders underneath +app/controllers+. The +:controller+ option provides a convenient way to use these routes. For example, you might have a resource whose controller is purely for admin users in the +admin+ folder:
+
+[source, ruby]
+-------------------------------------------------------
+map.resources :adminphotos, :controller => "admin/photos"
+-------------------------------------------------------
+
+If you use controller namespaces, you need to be aware of a subtlety in the Rails routing code: it always tries to preserve as much of the namespace from the previous request as possible. For example, if you are on a view generated from the +adminphoto_path+ helper, and you follow a link generated with +<%= link_to "show", adminphoto(1) %> you will end up on the view generated by +admin/photos/show+ but you will also end up in the same place if you have +<%= link_to "show", {:controller => "photos", :action => "show"} %>+ because Rails will generate the show URL relative to the current URL.
+
+TIP: If you want to guarantee that a link goes to a top-level controller, use a preceding slash to anchor the controller name: +<%= link_to "show", {:controller => "/photos", :action => "show"} %>+
+
 ==== Using :singular
 
 If for some reason Rails isn't doing what you want in converting the plural resource name to a singular name in member routes, you can override its judgment with the +:singular+ option:
@@ -892,3 +905,4 @@ assert_routing { :path => "photos", :method => :post }, { :controller => "photos
 http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/3[Lighthouse ticket]
 
 * September 10, 2008: initial version by link:../authors.html#mgunderloy[Mike Gunderloy]
+* September 23, 2008: Added section on namespaced controllers and routing, by link:../authors.html#mgunderloy[Mike Gunderloy]
\ No newline at end of file