Skip to content
This repository
Browse code

Rework the routing documentation.

Move the default route to the bottom, as this practise should be discouraged.
Add documentation for resources, external redirects and Rack applications.
  • Loading branch information...
commit 5ead15b07597e9cdb887cfe6aa74de4a14140bb1 1 parent 4b14de7
Joost Baaij authored August 28, 2010

Showing 1 changed file with 75 additions and 22 deletions. Show diff stats Hide diff stats

  1. 97  actionpack/lib/action_dispatch/routing.rb
97  actionpack/lib/action_dispatch/routing.rb
@@ -2,31 +2,11 @@
2 2
 require 'active_support/core_ext/regexp'
3 3
 
4 4
 module ActionDispatch
5  
-  # = Routing
6  
-  #
7 5
   # The routing module provides URL rewriting in native Ruby. It's a way to
8 6
   # redirect incoming requests to controllers and actions. This replaces
9  
-  # mod_rewrite rules. Best of all, Rails' Routing works with any web server.
  7
+  # mod_rewrite rules. Best of all, Rails' \Routing works with any web server.
10 8
   # Routes are defined in <tt>config/routes.rb</tt>.
11 9
   #
12  
-  # Consider the following route, which you will find commented out at the
13  
-  # bottom of your generated <tt>config/routes.rb</tt>:
14  
-  #
15  
-  #   match ':controller(/:action(/:id(.:format)))'
16  
-  #
17  
-  # This route states that it expects requests to consist of a
18  
-  # <tt>:controller</tt> followed optionally by an <tt>:action</tt> that in
19  
-  # turn is followed optionally by an <tt>:id</tt>, which in turn is followed
20  
-  # optionally by a <tt>:format</tt>
21  
-  #
22  
-  # Suppose you get an incoming request for <tt>/blog/edit/22</tt>, you'll end
23  
-  # up with:
24  
-  #
25  
-  #   params = { :controller => 'blog',
26  
-  #              :action     => 'edit',
27  
-  #              :id         => '22'
28  
-  #           }
29  
-  #
30 10
   # Think of creating routes as drawing a map for your requests. The map tells
31 11
   # them where to go based on some predefined pattern:
32 12
   #
@@ -43,6 +23,39 @@ module ActionDispatch
43 23
   #
44 24
   # Other names simply map to a parameter as in the case of <tt>:id</tt>.
45 25
   #
  26
+  # == Resources
  27
+  #
  28
+  # Resource routing allows you to quickly declare all of the common routes
  29
+  # for a given resourceful controller. Instead of declaring separate routes
  30
+  # for your +index+, +show+, +new+, +edit+, +create+, +update+ and +destroy+
  31
+  # actions, a resourceful route declares them in a single line of code:
  32
+  #
  33
+  #  resources :photos
  34
+  #
  35
+  # Sometimes, you have a resource that clients always look up without
  36
+  # referencing an ID. A common example, /profile always shows the profile of
  37
+  # the currently logged in user. In this case, you can use a singular resource
  38
+  # to map /profile (rather than /profile/:id) to the show action.
  39
+  #
  40
+  #  resource :profile
  41
+  #
  42
+  # It's common to have resources that are logically children of other
  43
+  # resources:
  44
+  #
  45
+  #   resources :magazines do
  46
+  #     resources :ads
  47
+  #   end
  48
+  #
  49
+  # You may wish to organize groups of controllers under a namespace. Most
  50
+  # commonly, you might group a number of administrative controllers under
  51
+  # an +admin+ namespace. You would place these controllers under the
  52
+  # app/controllers/admin directory, and you can group them together in your
  53
+  # router:
  54
+  #
  55
+  #   namespace "admin" do
  56
+  #     resources :posts, :comments
  57
+  #   end
  58
+  #
46 59
   # == Named routes
47 60
   #
48 61
   # Routes can be named by passing an <tt>:as</tt> option,
@@ -131,6 +144,30 @@ module ActionDispatch
131 144
   # Encoding regular expression modifiers are silently ignored. The
132 145
   # match will always use the default encoding or ASCII.
133 146
   #
  147
+  # == Default route
  148
+  #
  149
+  # Consider the following route, which you will find commented out at the
  150
+  # bottom of your generated <tt>config/routes.rb</tt>:
  151
+  #
  152
+  #   match ':controller(/:action(/:id(.:format)))'
  153
+  #
  154
+  # This route states that it expects requests to consist of a
  155
+  # <tt>:controller</tt> followed optionally by an <tt>:action</tt> that in
  156
+  # turn is followed optionally by an <tt>:id</tt>, which in turn is followed
  157
+  # optionally by a <tt>:format</tt>.
  158
+  #
  159
+  # Suppose you get an incoming request for <tt>/blog/edit/22</tt>, you'll end
  160
+  # up with:
  161
+  #
  162
+  #   params = { :controller => 'blog',
  163
+  #              :action     => 'edit',
  164
+  #              :id         => '22'
  165
+  #           }
  166
+  #
  167
+  # By not relying on default routes, you improve the security of your
  168
+  # application since not all controller actions, which includes actions you
  169
+  # might add at a later time, are exposed by default.
  170
+  #
134 171
   # == HTTP Methods
135 172
   #
136 173
   # Using the <tt>:via</tt> option when specifying a route allows you to restrict it to a specific HTTP method.
@@ -160,6 +197,20 @@ module ActionDispatch
160 197
   # however if your route needs to respond to more than one HTTP method (or all methods) then using the
161 198
   # <tt>:via</tt> option on <tt>match</tt> is preferable.
162 199
   #
  200
+  # == External redirects
  201
+  #
  202
+  # You can redirect any path to another path using the redirect helper in your router:
  203
+  #
  204
+  #   match "/stories" => redirect("/posts")
  205
+  #
  206
+  # == Routing to Rack Applications
  207
+  #
  208
+  # Instead of a String, like <tt>posts#index</tt>, which corresponds to the
  209
+  # index action in the PostsController, you can specify any Rack application
  210
+  # as the endpoint for a matcher:
  211
+  #
  212
+  #   match "/application.js" => Sprockets
  213
+  #
163 214
   # == Reloading routes
164 215
   #
165 216
   # You can reload routes if you feel you must:
@@ -208,7 +259,9 @@ module ActionDispatch
208 259
   #
209 260
   # == View a list of all your routes
210 261
   #
211  
-  # Run <tt>rake routes</tt>.
  262
+  #   rake routes
  263
+  #
  264
+  # Target specific controllers by prefixing the command with <tt>CONTROLLER=x</tt>.
212 265
   #
213 266
   module Routing
214 267
     autoload :DeprecatedMapper, 'action_dispatch/routing/deprecated_mapper'

0 notes on commit 5ead15b

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