diff options
Diffstat (limited to 'actionpack/lib/action_dispatch')
-rw-r--r-- | actionpack/lib/action_dispatch/routing.rb | 152 |
1 files changed, 47 insertions, 105 deletions
diff --git a/actionpack/lib/action_dispatch/routing.rb b/actionpack/lib/action_dispatch/routing.rb index b598d6f7e2..335c9edb98 100644 --- a/actionpack/lib/action_dispatch/routing.rb +++ b/actionpack/lib/action_dispatch/routing.rb @@ -9,17 +9,18 @@ module ActionDispatch # mod_rewrite rules. Best of all, Rails' Routing works with any web server. # Routes are defined in <tt>config/routes.rb</tt>. # - # Consider the following route, installed by Rails when you generate your - # application: + # Consider the following route, which you will find commented out at the + # bottom of your generated <tt>config/routes.rb</tt>: # - # map.connect ':controller/:action/:id' + # match ':controller(/:action(/:id(.:format)))' # # This route states that it expects requests to consist of a - # <tt>:controller</tt> followed by an <tt>:action</tt> that in turn is fed - # some <tt>:id</tt>. + # <tt>:controller</tt> followed optionally by an <tt>:action</tt> that in + # turn is followed optionally by an <tt>:id</tt>, which in turn is followed + # optionally by a <tt>:format</tt> # - # Suppose you get an incoming request for <tt>/blog/edit/22</tt>, you'll end up - # with: + # Suppose you get an incoming request for <tt>/blog/edit/22</tt>, you'll end + # up with: # # params = { :controller => 'blog', # :action => 'edit', @@ -29,7 +30,7 @@ module ActionDispatch # 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| + # AppName::Applications.routes.draw do |map| # Pattern 1 tells some request to go to one place # Pattern 2 tell them to go to another # ... @@ -42,60 +43,16 @@ module ActionDispatch # # Other names simply map to a parameter as in the case of <tt>:id</tt>. # - # == Route priority - # - # Not all routes are created equally. Routes have priority defined by the - # order of appearance of the routes in the <tt>config/routes.rb</tt> file. The priority goes - # from top to bottom. The last route in that file is at the lowest priority - # and will be applied last. If no route matches, 404 is returned. - # - # Within blocks, the empty pattern 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 - you simply append a - # Hash at the end of your mapping to set any 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 include arbitrary parameters in the route, thus: - # - # map.connect ':controller/:action/:id', :action => 'show', :page => 'Dashboard' - # - # This will pass the :page parameter to all incoming requests that match this route. - # - # Note: The default routes, as provided by the Rails generator, make all actions in every - # controller accessible via GET requests. You should consider removing them or commenting - # them out if you're using named routes and resources. - # # == Named routes # - # Routes can be named with the syntax <tt>map.name_of_route options</tt>, + # Routes can be named by passing an <tt>:as</tt> option, # allowing for easy reference within your source as +name_of_route_url+ # for the full URL and +name_of_route_path+ for the URI path. # # Example: # # # In routes.rb - # map.login 'login', :controller => 'accounts', :action => 'login' + # match '/login' => 'accounts#login', :as => 'login' # # # With render, redirect_to, tests, etc. # redirect_to login_url @@ -104,10 +61,10 @@ module ActionDispatch # # redirect_to show_item_path(:id => 25) # - # Use <tt>map.root</tt> as a shorthand to name a route for the root path "". + # Use <tt>root</tt> as a shorthand to name a route for the root path "". # # # In routes.rb - # map.root :controller => 'blogs' + # root :to => 'blogs#index' # # # would recognize http://www.example.com/ as # params = { :controller => 'blogs', :action => 'index' } @@ -116,20 +73,14 @@ module ActionDispatch # root_url # => 'http://www.example.com/' # root_path # => '' # - # You can also specify an already-defined named route in your <tt>map.root</tt> call: - # - # # In routes.rb - # map.new_session :controller => 'sessions', :action => 'new' - # map.root :new_session - # - # Note: when using +with_options+, the route is simply named after the + # Note: when using +controller+, the route is simply named after the # method you call on the block parameter rather than map. # # # In routes.rb - # map.with_options :controller => 'blog' do |blog| - # blog.show '', :action => 'list' - # blog.delete 'delete/:id', :action => 'delete' - # blog.edit 'edit/:id', :action => 'edit' + # controller :blog do + # match 'blog/show' => :list + # match 'blog/delete' => :delete + # match 'blog/edit/:id' => :edit # end # # # provides named routes for show, delete, and edit @@ -139,12 +90,13 @@ module ActionDispatch # # 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}/ + # match '/articles/:year/:month/:day', :constraints => { + # :controller => 'articles', + # :action => 'find_by_date', + # :year => /\d{4}/, + # :month => /\d{1,2}/, + # :day => /\d{1,2}/ + # } # # Using the route above, the URL "http://localhost:3000/articles/2005/11/06" # maps to @@ -154,42 +106,34 @@ module ActionDispatch # == Regular Expressions and parameters # You can specify a regular expression to define a format for a parameter. # - # map.geocode 'geocode/:postalcode', :controller => 'geocode', - # :action => 'show', :postalcode => /\d{5}(-\d{4})?/ - # - # or, more formally: + # controller 'geocode' do + # match 'geocode/:postalcode' => :show', :constraints => { + # :postalcode => /\d{5}(-\d{4})?/ + # } # - # map.geocode 'geocode/:postalcode', :controller => 'geocode', - # :action => 'show', :requirements => { :postalcode => /\d{5}(-\d{4})?/ } - # - # Formats can include the 'ignorecase' and 'extended syntax' regular + # Constraints can include the 'ignorecase' and 'extended syntax' regular # expression modifiers: # - # map.geocode 'geocode/:postalcode', :controller => 'geocode', - # :action => 'show', :postalcode => /hx\d\d\s\d[a-z]{2}/i + # controller 'geocode' do + # match 'geocode/:postalcode' => :show', :constraints => { + # :postalcode => /hx\d\d\s\d[a-z]{2}/i + # } + # end # - # map.geocode 'geocode/:postalcode', :controller => 'geocode', - # :action => 'show',:requirements => { - # :postalcode => /# Postcode format - # \d{5} #Prefix - # (-\d{4})? #Suffix - # /x - # } + # controller 'geocode' do + # match 'geocode/:postalcode' => :show', :constraints => { + # :postalcode => /# Postcode format + # \d{5} #Prefix + # (-\d{4})? #Suffix + # /x + # } + # end # # Using the multiline match modifier will raise an ArgumentError. # Encoding regular expression modifiers are silently ignored. The # match will always use the default encoding or ASCII. # - # == 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. - # The globbed values are in <tt>params[:path]</tt> as an array of path segments. - # - # == Route conditions + # == HTTP Methods # # With conditions you can define restrictions on routes. Currently the only valid condition is <tt>:method</tt>. # @@ -200,10 +144,8 @@ module ActionDispatch # # Example: # - # map.connect 'post/:id', :controller => 'posts', :action => 'show', - # :conditions => { :method => :get } - # map.connect 'post/:id', :controller => 'posts', :action => 'create_comment', - # :conditions => { :method => :post } + # get 'post/:id' => 'posts#show' + # post 'post/:id' => "posts#create_comment' # # Now, if you POST to <tt>/posts/:id</tt>, it will route to the <tt>create_comment</tt> action. A GET on the same # URL will route to the <tt>show</tt> action. @@ -212,7 +154,7 @@ module ActionDispatch # # You can reload routes if you feel you must: # - # ActionController::Routing::Routes.reload + # Rails::Application.reload_routes! # # This will clear all named routes and reload routes.rb if the file has been modified from # last load. To absolutely force reloading, use <tt>reload!</tt>. |