Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

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

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@5000 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
commit 40c86a7bda56e1927468618bf11fbe30fb9d6ed3 1 parent 9514e4e
@dhh dhh authored
Showing with 188 additions and 0 deletions.
  1. +188 −0 actionpack/lib/action_controller/routing.rb
View
188 actionpack/lib/action_controller/routing.rb
@@ -47,6 +47,193 @@ def unoptionalize(pattern)
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 @@ def extract_request_environment(request)
Routes = RouteSet.new
end
end
+
Please sign in to comment.
Something went wrong with that request. Please try again.