Documentation for routes (closes #5165) [rramdas@gmail.com]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@5000 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

actionpack/lib/action_controller/routing.rb

@@ -47,6 +47,193 @@ class Regexp
 end
 
 module ActionController
+  # == Routing 
+  #
+  # The routing module provides URL rewriting in native Ruby. It's a way to
+  # redirect incoming requests to controllers and actions. This replaces
+  # mod_rewrite rules. Best of all Rails' Routing works with any web server. 
+  # Routes are defined in routes.rb in your RAILS_ROOT/config directory.
+  #
+  # Consider the following route, installed by Rails when you generate your 
+  # application:
+  #
+  #   map.connect ':controller/:action/:id'
+  #
+  # This route states that it expects requests to consist of a 
+  # :controller followed by an :action that in turns is fed by some :id 
+  #
+  # Suppose you get an incoming request for <tt>/blog/edit/22</tt>, you'll end up 
+  # with:
+  #
+  #   params = { :controller => 'blog',
+  #              :action     => 'edit' 
+  #              :id         => '22'
+  #           }
+  #
+  # Think of creating routes as drawing a map for your requests. The map tells 
+  # them where to go based on some predefined pattern:
+  #
+  #  ActionController::Routing::Routes.draw do |map|
+  #   Pattern 1 tells some request to go to one place
+  #   Pattern 2 tell them to go to another
+  #   ...
+  #  end
+  #
+  # The following symbols are special:
+  #
+  #   :controller maps to your controller name
+  #   :action     maps to an action with your controllers
+  #   
+  # Other names simply map to a parameter as in the case of +:id+.
+  #    
+  # == Route priority
+  #
+  # Not all routes are created equally. Routes have priority defined by the 
+  # order of appearance of the routes in the routes.rb file. The priority goes
+  # from top to bottom. The last route in that file is at the lowest priority
+  # will be applied last. If no route matches, 404 is returned.
+  #
+  # Within blocks, the empty pattern goes first i.e. is at the highest priority.
+  # In practice this works out nicely:
+  #
+  #  ActionController::Routing::Routes.draw do |map| 
+  #    map.with_options :controller => 'blog' do |blog|
+  #      blog.show    '',  :action => 'list'
+  #    end
+  #    map.connect ':controller/:action/:view 
+  #  end
+  #
+  # In this case, invoking blog controller (with an URL like '/blog/') 
+  # without parameters will activate the 'list' action by default.
+  #
+  # == Defaults routes and default parameters
+  #
+  # Setting a default route is straightforward in Rails because by appending a
+  # Hash to the end of your mapping you can set default parameters.
+  #
+  # Example:
+  #  ActionController::Routing:Routes.draw do |map|
+  #    map.connect ':controller/:action/:id', :controller => 'blog'
+  #  end
+  #
+  # This sets up  +blog+ as the default controller if no other is specified. 
+  # This means visiting '/' would invoke the blog controller.
+  #
+  # More formally, you can define defaults in a route with the +:defaults+ key.
+  #   
+  #   map.connect ':controller/:id/:action', :action => 'show', :defaults => { :page => 'Dashboard' }
+  #
+  # == Named routes
+  #
+  # Routes can be named with the syntax <tt>map.name_of_route options</tt>,
+  # allowing for easy reference within your source as +name_of_route_url+.
+  #
+  # Example:
+  #   # In routes.rb
+  #   map.login 'login', :controller => 'accounts', :action => 'login'
+  #
+  #   # With render, redirect_to, tests, etc.
+  #   redirect_to login_url
+  #
+  # Arguments can be passed as well.
+  #
+  #   redirect_to show_item_url(:id => 25)
+  #
+  # When using +with_options+, the name goes after the item passed to the block.
+  #
+  #  ActionController::Routing::Routes.draw do |map| 
+  #    map.with_options :controller => 'blog' do |blog|
+  #      blog.show    '',            :action  => 'list'
+  #      blog.delete  'delete/:id',  :action  => 'delete',
+  #      blog.edit    'edit/:id',    :action  => 'edit'
+  #    end
+  #    map.connect ':controller/:action/:view 
+  #  end
+  #
+  # You would then use the named routes in your views:
+  #
+  #   link_to @article.title, show_url(:id => @article.id) 
+  #
+  # == Pretty URL's
+  #
+  # Routes can generate pretty URLs. For example:
+  #
+  #  map.connect 'articles/:year/:month/:day',
+  #   	         :controller => 'articles', 
+  #              :action     => 'find_by_date',
+  #              :year       => /\d{4}/,
+  #              :month => /\d{1,2}/, 
+  #              :day   => /\d{1,2}/
+  #  
+  #  # Using the route above, the url below maps to:
+  #  # params = {:year => '2005', :month => '11', :day => '06'}
+  #  # http://localhost:3000/articles/2005/11/06
+  #
+  # == Regular Expressions and parameters
+  # You can specify a reqular expression to define a format for a parameter.
+  #
+  #  map.geocode 'geocode/:postalcode', :controller => 'geocode',
+  #              :action => 'show', :postalcode => /\d{5}(-\d{4})?/
+  #
+  # or  more formally:
+  #
+  #   map.geocode 'geocode/:postalcode', :controller => 'geocode', 
+  #                      :action => 'show', 
+  #                      :requirements { :postalcode => /\d{5}(-\d{4})?/ }
+  #
+  # == Route globbing
+  #
+  # Specifying <tt>*[string]</tt> as part of a rule like :
+  #
+  #  map.connect '*path' , :controller => 'blog' , :action => 'unrecognized?'
+  #
+  # will glob all remaining parts of the route that were not recognized earlier. This idiom must appear at the end of the path. The globbed values are in <tt>params[:path]</tt> in this case.  
+  #
+  # == Reloading routes
+  #
+  # You can reload routes if you feel you must:
+  #
+  #  Action::Controller::Routes.reload
+  #
+  # This will clear all named routes and reload routes.rb
+  #
+  # == Testing Routes
+  #
+  # The two main methods for testing your routes:
+  #
+  # === +assert_routing+
+  # 
+  #  def test_movie_route_properly_splits
+  #   opts = {:controller => "plugin", :action => "checkout", :id => "2"}
+  #   assert_routing "plugin/checkout/2", opts
+  #  end
+  #  
+  # +assert_routing+ lets you test whether or not the route properly resolves into options.
+  #
+  # === +assert_recognizes+
+  #
+  #  def test_route_has_options
+  #   opts = {:controller => "plugin", :action => "show", :id => "12"}
+  #   assert_recognizes opts, "/plugins/show/12" 
+  #  end
+  # 
+  # Note the subtle difference between the two: +assert_routing+ tests that
+  # an URL fits options while +assert_recognizes+ tests that an URL
+  # breaks into parameters properly.
+  #
+  # In tests you can simply pass the URL or named route to +get+ or +post+.
+  #
+  #  def send_to_jail
+  #    get '/jail'
+  #    assert_response :success
+  #    assert_template "jail/front"
+  #  end
+  #
+  #  def goes_to_login
+  #    get login_url
+  #    #...
+  #  end
+  #
   module Routing
     SEPARATORS = %w( / ; . , ? )
 
@@ -1091,3 +1278,4 @@ module ActionController
     Routes = RouteSet.new
   end
 end
+