@@ -5,14 +5,14 @@ This guide covers the user-facing features of Rails routing. By referring to thi
* Understand the code in +routes.rb+
* Construct your own routes, using either the preferred resourceful style or with the @match@ method
* Identify what parameters to expect an action to receive
* Automatically create URLs using route helpers
* Automatically create paths and URLs using route helpers
* Use advanced techniques such as constraints and Rack endpoints
endprologue.
h3. The Purpose of the Rails Router
The Rails router recognizes URLs and dispatches them to a controller's action. It can also generate URLs, avoiding the need to hardcode URL strings in your views.
The Rails router recognizes URLs and dispatches them to a controller's action. It can also generate paths and URLs, avoiding the need to hardcode strings in your views.
h4. Connecting URLs to Code
...
...
@@ -30,9 +30,9 @@ match "/patients/:id" => "patients#show"
the request is dispatched to the +patients+ controller's +show+ action with <tt>{ :id => "17" }</tt> in +params+.
h4. Generating URLs from Code
h4. Generating Paths and URLs from Code
You can also generate URLs. If your application contains this code:
You can also generate paths and URLs. If your application contains this code:
<ruby>
@patient = Patient.find(17)
...
...
@@ -76,7 +76,7 @@ resources :photos
creates seven different routes in your application, all mapping to the +Photos+ controller:
|_. Verb |_.URL |_.action |_.used for|
|_. Verb |_.Path |_.action |_.used for|
|GET |/photos |index |display a list of all photos|
|GET |/photos/new |new |return an HTML form for creating a new photo|
|POST |/photos |create |create a new photo|
...
...
@@ -85,7 +85,7 @@ creates seven different routes in your application, all mapping to the +Photos+
|PUT |/photos/:id |update |update a specific photo|
|DELETE |/photos/:id |destroy |delete a specific photo|
h4. URLs and Paths
h4. Paths and URLs
Creating a resourceful route will also expose a number of helpers to the controllers in your application. In the case of +resources :photos+:
...
...
@@ -130,7 +130,7 @@ resource :geocoder
creates six different routes in your application, all mapping to the +Geocoders+ controller:
|_. Verb |_.URL |_.action |_.used for|
|_. Verb |_.Path |_.action |_.used for|
|GET |/geocoder/new |new |return an HTML form for creating the geocoder|
|POST |/geocoder |create |create the new geocoder|
|GET |/geocoder |show |display the one and only geocoder resource|
...
...
@@ -160,7 +160,7 @@ end
This will create a number of routes for each of the +posts+ and +comments+ controller. For +Admin::PostsController+, Rails will create:
In each of these cases, the named routes remain the same as if you did not use +scope+. In the last case, the following URLs map to +PostsController+:
In each of these cases, the named routes remain the same as if you did not use +scope+. In the last case, the following paths map to +PostsController+:
In addition to the routes for magazines, this declaration will also route ads to an +AdsController+. The ad URLs require a magazine:
|_.Verb |_.URL |_.action |_.used for|
|_.Verb |_.Path |_.action |_.used for|
|GET |/magazines/1/ads |index |display a list of all ads for a specific magazine|
|GET |/magazines/1/ads/new |new |return an HTML form for creating a new ad belonging to a specific magazine|
|POST |/magazines/1/ads |create |create a new ad belonging to a specific magazine|
...
...
@@ -256,7 +256,7 @@ resources :publishers do
end
</ruby>
Deeply-nested resources quickly become cumbersome. In this case, for example, the application would recognize URLs such as
Deeply-nested resources quickly become cumbersome. In this case, for example, the application would recognize paths such as
<pre>
/publishers/1/magazines/2/photos/3
...
...
@@ -266,9 +266,9 @@ The corresponding route helper would be +publisher_magazine_photo_url+, requirin
TIP: _Resources should never be nested more than 1 level deep._
h4. Creating URLs From Objects
h4. Creating Paths and URLs From Objects
In addition to using the routing helpers, Rails can also create URLs from an array of parameters. For example, suppose you have this set of routes:
In addition to using the routing helpers, Rails can also create paths and URLs from an array of parameters. For example, suppose you have this set of routes:
<ruby>
resources :magazines do
...
...
@@ -340,7 +340,7 @@ resources :photos do
end
</ruby>
This will enable Rails to recognize URLs such as +/photos/search+ with GET, and route to the +search+ action of +PhotosController+. It will also create the +search_photos_url+ and +search_photos_path+ route helpers.
This will enable Rails to recognize paths such as +/photos/search+ with GET, and route to the +search+ action of +PhotosController+. It will also create the +search_photos_url+ and +search_photos_path+ route helpers.
Just as with member routes, you can pass +:on+ to a route:
...
...
@@ -380,7 +380,7 @@ You can set up as many dynamic segments within a regular route as you like. Anyt
match ':controller/:action/:id/:user_id'
</ruby>
An incoming URL of +/photos/show/1/2+ will be dispatched to the +show+ action of the +PhotosController+. +params[:id]+ will be +"1"+, and +params[:user_id]+ will be +"2"+.
An incoming path of +/photos/show/1/2+ will be dispatched to the +show+ action of the +PhotosController+. +params[:id]+ will be +"1"+, and +params[:user_id]+ will be +"2"+.
NOTE: You can't use +namespace+ or +:module+ with a +:controller+ path segment. If you need to do this then use a constraint on :controller that matches the namespace you require. e.g:
...
...
@@ -396,7 +396,7 @@ You can specify static segments when creating a route:
match ':controller/:action/:id/with_user/:user_id'
</ruby>
This route would respond to URLs such as +/photos/show/1/with_user/2+. In this case, +params+ would be <tt>{ :controller => "photos", :action => "show", :id => "1", :user_id => "2" }</tt>.
This route would respond to paths such as +/photos/show/1/with_user/2+. In this case, +params+ would be <tt>{ :controller => "photos", :action => "show", :id => "1", :user_id => "2" }</tt>.
h4. The Query String
...
...
@@ -406,7 +406,7 @@ The +params+ will also include any parameters from the query string. For example
match ':controller/:action/:id'
</ruby>
An incoming URL of +/photos/show/1?user_id=2+ will be dispatched to the +show+ action of the +Photos+ controller. +params+ will be <tt>{ :controller => "photos", :action => "show", :id => "1", :user_id => "2" }</tt>.
An incoming path of +/photos/show/1?user_id=2+ will be dispatched to the +show+ action of the +Photos+ controller. +params+ will be <tt>{ :controller => "photos", :action => "show", :id => "1", :user_id => "2" }</tt>.
h4. Defining Defaults
...
...
@@ -416,7 +416,7 @@ You do not need to explicitly use the +:controller+ and +:action+ symbols within
match 'photos/:id' => 'photos#show'
</ruby>
With this route, Rails will match an incoming URL of +/photos/12+ to the +show+ action of +PhotosController+.
With this route, Rails will match an incoming path of +/photos/12+ to the +show+ action of +PhotosController+.
You can also define other defaults in a route by supplying a hash for the +:defaults+ option. This even applies to parameters that you do not specify as dynamic segments. For example:
...
...
@@ -444,7 +444,7 @@ You can use the +:constraints+ option to enforce a format for a dynamic segment: