Permalink
Browse files

improve routing docs, mostly for #match

  • Loading branch information...
1 parent c56e314 commit 277327bb7f389a140eb4ae7722d64d6cf45e06cf @cldwalker cldwalker committed Feb 5, 2011
Showing with 34 additions and 12 deletions.
  1. +34 −12 actionpack/lib/action_dispatch/routing/mapper.rb
@@ -247,7 +247,7 @@ def initialize(set) #:nodoc:
#
# root :to => 'pages#main'
#
- # For options, see the +match+ method's documentation, as +root+ uses it internally.
+ # For options, see +match+, as +root+ uses it internally.
#
# You should put the root route at the top of <tt>config/routes.rb</tt>,
# because this means it will be matched first. As this is the most popular route
@@ -256,25 +256,42 @@ def root(options = {})
match '/', options.reverse_merge(:as => :root)
end
- # Matches a pattern to one or more urls. Any symbols in a pattern are
- # interpreted as url parameters:
+ # Matches a url pattern to one or more routes. Any symbols in a pattern
+ # are interpreted as url query parameters and thus available as +params+
+ # in an action:
#
- # # sets parameters :controller, :action and :id
+ # # sets :controller, :action and :id in params
# match ':controller/:action/:id'
#
- # Two of these symbols are special: <tt>:controller</tt> maps to the
- # controller name and <tt>:action</tt> to the action name within that
- # controller. Anything other than <tt>:controller</tt> or
- # <tt>:action</tt> will be available to the action as part of +params+.
- # If a pattern does not have :controller and :action symbols, then they
- # must be set in options or shorthand. For example:
+ # Two of these symbols are special, +:controller+ maps to the controller
+ # and +:action+ to the controller's action. A pattern can also map
+ # wildcard segments (globs) to params:
+ #
+ # match 'songs/*category/:title' => 'songs#show'
+ #
+ # # 'songs/rock/classic/stairway-to-heaven' sets
+ # # params[:category] = 'rock/classic'
+ # # params[:title] = 'stairway-to-heaven'
+ #
+ # When a pattern points to an internal route, the route's +:action+ and
+ # +:controller+ should be set in options or hash shorthand. Examples:
#
# match 'photos/:id' => 'photos#show'
# match 'photos/:id', :to => 'photos#show'
# match 'photos/:id', :controller => 'photos', :action => 'show'
#
+ # A pattern can also point to a +Rack+ endpoint i.e. anything that
+ # responds to +call+:
+ #
+ # match 'photos/:id' => lambda {|hash| [200, {}, "Coming soon" }
+ # match 'photos/:id' => PhotoRackApp
+ # # Yes, controller actions are just rack endpoints
+ # match 'photos/:id' => PhotosController.action(:show)
+ #
# === Options
#
+ # Any options not seen here are passed on as params with the url.
+ #
# [:controller]
# The route's controller.
#
@@ -302,9 +319,12 @@ def root(options = {})
# match 'path' => 'c#a', :via => [:get, :post]
#
# [:to]
- # Shorthand for specifying :controller and :action.
+ # Points to a +Rack+ endpoint. Can be an object that responds to
+ # +call+ or a string representing a controller's action.
#
- # match 'path' => 'c#a', :to => 'controller#action'
+ # match 'path', :to => 'controller#action'
+ # match 'path', :to => lambda { [200, {}, "Success!"] }
+ # match 'path', :to => RackApp
#
# [:on]
# Shorthand for wrapping routes in a specific RESTful context. Valid
@@ -358,6 +378,8 @@ def match(path, options=nil)
#
# mount(SomeRackApp => "some_route")
#
+ # For options, see +match+, as +mount+ uses it internally.
+ #
# All mounted applications come with routing helpers to access them.
# These are named after the class specified, so for the above example
# the helper is either +some_rack_app_path+ or +some_rack_app_url+.

0 comments on commit 277327b

Please sign in to comment.