From 40c86a7bda56e1927468618bf11fbe30fb9d6ed3 Mon Sep 17 00:00:00 2001 From: David Heinemeier Hansson Date: Mon, 4 Sep 2006 20:34:19 +0000 Subject: 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 | 188 ++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_controller/routing.rb b/actionpack/lib/action_controller/routing.rb index ab15e66e5c..1650c86b2a 100644 --- a/actionpack/lib/action_controller/routing.rb +++ b/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 /blog/edit/22, 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 map.name_of_route options, + # 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 *[string] 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 params[:path] 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 + -- cgit v1.2.3