RubyGems - railties - Versions diffs - 3.0.0.beta2 → 3.0.0.beta3 - Mend

railties 3.0.0.beta2 → 3.0.0.beta3

Files changed (147) hide show

data/guides/source/layout.html.erb CHANGED

@@ -1,19 +1,27 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
 <title><%= yield(:page_title) || 'Ruby on Rails guides' %></title>
-<link rel="stylesheet" type="text/css" href="files/stylesheets/style.css" />
-<link rel="stylesheet" type="text/css" href="files/stylesheets/syntax.css" />
-<link rel="stylesheet" type="text/css" href="files/stylesheets/print.css" media="print" />
+<link rel="stylesheet" type="text/css" href="stylesheets/style.css" />
+<link rel="stylesheet" type="text/css" href="stylesheets/syntax.css" />
+<link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print" />
-<script type="text/javascript" src="files/javascripts/guides.js"></script>
-<script type="text/javascript" src="files/javascripts/code_highlighter.js"></script>
-<script type="text/javascript" src="files/javascripts/highlighters.js"></script>
+<script type="text/javascript" src="javascripts/guides.js"></script>
+<script type="text/javascript" src="javascripts/code_highlighter.js"></script>
+<script type="text/javascript" src="javascripts/highlighters.js"></script>
 </head>
 <body class="guide">
+  <% if @edge %>
+  <div>
+    <img src="images/edge_badge.png" alt="edge-badge" id="edge-badge" />
+  </div>
+  <% end %>
   <div id="topNav">
     <div class="wrapper">
       <strong>More at <a href="http://rubyonrails.org/">rubyonrails.org:</a> </strong>
@@ -101,7 +109,7 @@
   <hr class="hide" />
   <div id="footer">
     <div class="wrapper">
-      <p>This work is licensed under a <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-Share Alike 3.0</a> License</a></p>
+      <p>This work is licensed under a <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-Share Alike 3.0</a> License</p>
       <p>"Rails", "Ruby on Rails", and the Rails logo are trademarks of David Heinemeier Hansson. All rights reserved.</p>
     </div>
   </div>

data/guides/source/layouts_and_rendering.textile CHANGED

@@ -510,7 +510,7 @@ def show
 end
 </ruby>
-Make sure you use +and return+ and not +&& return+ because while the former will work, the latter will not due to operator precedence in the Ruby Language.
+Make sure you use +and return+ and not +&amp;&amp; return+ because while the former will work, the latter will not due to operator precedence in the Ruby Language.
 Note that the implicit render done by ActionController detects if +render+ has been called, and thus avoids this error. Therefore, the following will work without errors:
@@ -747,7 +747,7 @@ You can even use dynamic paths such as +cache/#{current_site}/main/display+.
 h5. Linking to CSS Files with +stylesheet_link_tag+
-The +stylesheet_link_tag+ helper returns an HTML +<link>+ tag for each source provided. Rails looks in +public/stylesheets+ for these files by default, but you can specify a full path relative to the document root, or a URL, if you prefer. For example, to include +public/stylesheets/main.cs+:
+The +stylesheet_link_tag+ helper returns an HTML +&lt;link&gt;+ tag for each source provided. Rails looks in +public/stylesheets+ for these files by default, but you can specify a full path relative to the document root, or a URL, if you prefer. For example, to include +public/stylesheets/main.cs+:
 <erb>
 <%= stylesheet_link_tag "main" %>
@@ -1037,7 +1037,7 @@ You can also pass local variables into partials, making them even more powerful
 * +_form.html.erb+
 <erb>
-<% form_for(zone) do |f| %>
+<%= form_for(zone) do |f| %>
   <p>
     <b>Zone name</b><br />
     <%= f.text_field :name %>
@@ -1181,11 +1181,11 @@ On pages generated by +NewsController+, you want to hide the top menu and add a
 <% content_for :stylesheets do %>
   #top_menu {display: none}
   #right_menu {float: right; background-color: yellow; color: black}
-<% end -%>
+<% end %>
 <% content_for :content do %>
   <div id="right_menu">Right menu items here</div>
   <%= yield(:news_content) or yield %>
-<% end -%>
+<% end %>
 <%= render :file => 'layouts/application' %>
 </erb>
@@ -1197,6 +1197,7 @@ h3. Changelog
 "Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/15
+* April 4, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
 * January 25, 2010: Rails 3.0 Update by "Mikel Lindsaar":credits.html#raasdnil
 * December 27, 2008: Merge patch from Rodrigo Rosenfeld Rosas covering subtemplates
 * December 27, 2008: Information on new rendering defaults by "Mike Gunderloy":credits.html#mgunderloy

data/guides/source/nested_model_forms.textile CHANGED

@@ -122,7 +122,7 @@ h5. Standard form
 Start out with a regular RESTful form:
 <erb>
-<% form_for @person do |f| %>
+<%= form_for @person do |f| %>
   <%= f.text_field :name %>
 <% end %>
 </erb>
@@ -140,7 +140,7 @@ h5. Nested form for a single associated object
 Now add a nested form for the +address+ association:
 <erb>
-<% form_for @person do |f| %>
+<%= form_for @person do |f| %>
   <%= f.text_field :name %>
   <% f.fields_for :address do |af| %>
@@ -181,7 +181,7 @@ h5. Nested form for a collection of associated objects
 The form code for an association collection is pretty similar to that of a single associated object:
 <erb>
-<% form_for @person do |f| %>
+<%= form_for @person do |f| %>
   <%= f.text_field :name %>
   <% f.fields_for :projects do |pf| %>

data/guides/source/performance_testing.textile CHANGED

@@ -213,11 +213,11 @@ h4. Understanding the Output
 Performance tests generate different outputs inside +tmp/performance+ directory depending on their mode and metric.
-h5. Benchmarking
+h5(#output-benchmarking). Benchmarking
 In benchmarking mode, performance tests generate two types of outputs:
-h6. Command Line
+h6(#output-command-line). Command Line
 This is the primary form of output in benchmarking mode. Example:
@@ -258,7 +258,7 @@ measurement,created_at,app,rails,ruby,platform
 0.00771250000000012,2009-01-09T15:46:03Z,,2.3.0.master.859e150,ruby-1.8.6.110,i686-darwin9.0.0
 </shell>
-h5. Profiling
+h5(#output-profiling). Profiling
 In profiling mode, you can choose from four types of output.
@@ -330,7 +330,7 @@ h5. Apply the Patch
 h5. Configure and Install
-The following will install ruby in your home directory's +/rubygc+ directory. Make sure to replace +<homedir>+ with a full patch to your actual home directory.
+The following will install ruby in your home directory's +/rubygc+ directory. Make sure to replace +&lt;homedir&gt;+ with a full patch to your actual home directory.
 <shell>
 [lifo@null ruby-version]$ ./configure --prefix=/<homedir>/rubygc

data/guides/source/plugins.textile CHANGED

@@ -35,14 +35,14 @@ h4. Create the Basic Application
 The examples in this guide require that you have a working rails application.  To create a simple rails app execute:
-<pre>
+<shell>
 gem install rails
 rails yaffle_guide
 cd yaffle_guide
 rails generate scaffold bird name:string
 rake db:migrate
 rails server
-</pre>
+</shell>
 Then navigate to http://localhost:3000/birds.  Make sure you have a functioning rails app before continuing.
@@ -56,22 +56,22 @@ Rails ships with a plugin generator which creates a basic plugin skeleton. Pass
 This creates a plugin in 'vendor/plugins' including an 'init.rb' and 'README' as well as standard 'lib', 'task', and 'test' directories.
 Examples:
-<pre>
+<shell>
 rails generate plugin yaffle
 rails generate plugin yaffle --with-generator
-</pre>
+</shell>
 To get more detailed help on the plugin generator, type +rails generate plugin+.
 Later on this guide will describe how to work with generators, so go ahead and generate your plugin with the +--with-generator+ option now:
-<pre>
+<shell>
 rails generate plugin yaffle --with-generator
-</pre>
+</shell>
 You should see the following output:
-<pre>
+<shell>
 create  vendor/plugins/yaffle/lib
 create  vendor/plugins/yaffle/tasks
 create  vendor/plugins/yaffle/test
@@ -89,20 +89,20 @@ create  vendor/plugins/yaffle/generators/yaffle
 create  vendor/plugins/yaffle/generators/yaffle/templates
 create  vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb
 create  vendor/plugins/yaffle/generators/yaffle/USAGE
-</pre>
+</shell>
 h4. Organize Your Files
 To make it easy to organize your files and to make the plugin more compatible with GemPlugins, start out by altering your file system to look like this:
-<pre>
+<shell>
 |-- lib
 |   |-- yaffle
 |   `-- yaffle.rb
 `-- rails
     |
     `-- init.rb
-</pre>
+</shell>
 *vendor/plugins/yaffle/init.rb*
@@ -124,7 +124,7 @@ h4. Test Setup
 *vendor/plugins/yaffle/test/database.yml:*
-<pre>
+<yaml>
 sqlite:
   :adapter: sqlite
   :dbfile: vendor/plugins/yaffle/test/yaffle_plugin.sqlite.db
@@ -146,7 +146,7 @@ mysql:
   :username: root
   :password: password
   :database: yaffle_plugin_test
-</pre>
+</yaml>
 For this guide you'll need 2 tables/models, Hickwalls and Wickwalls, so add the following:
@@ -239,10 +239,10 @@ end
 To run this, go to the plugin directory and run +rake+:
-<pre>
+<shell>
 cd vendor/plugins/yaffle
 rake
-</pre>
+</shell>
 You should see output like:
@@ -1511,4 +1511,5 @@ h3. Changelog
 "Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213/tickets/32-update-plugins-guide
+* April 4, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
 * November 17, 2008: Major revision by Jeff Dean

data/guides/source/rails_on_rack.textile CHANGED

@@ -28,7 +28,7 @@ h3. Rails on Rack
 h4. Rails Application's Rack Object
-<tt>ActionController::Dispatcher.new</tt> is the primary Rack application object of a Rails application. Any Rack compliant web server should be using +ActionController::Dispatcher.new+ object to serve a Rails application.</p>
+<tt>ActionController::Dispatcher.new</tt> is the primary Rack application object of a Rails application. Any Rack compliant web server should be using +ActionController::Dispatcher.new+ object to serve a Rails application.
 h4. +rails server+

data/guides/source/routing.textile CHANGED

@@ -2,180 +2,111 @@ h2. Rails Routing from the Outside In
 This guide covers the user-facing features of Rails routing. By referring to this guide, you will be able to:
-* Understand the purpose of routing
-* Decipher the code in +routes.rb+
-* Construct your own routes, using either the @match@ method or the preferred RESTful style
-* Identify how a route will map to a controller and action
+* 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
+* Use advanced techniques such as constraints and Rack endpoints
 endprologue.
-h3. The Dual Purpose of Routing
+h3. The Purpose of the Rails Router
-Rails routing is a two-way piece of machinery - rather as if you could turn trees into paper, and then turn paper back into trees. Specifically, it both connects incoming HTTP requests to the code in your application's controllers, and helps you generate URLs without having to hard-code them as strings.
+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.
 h4. Connecting URLs to Code
-When your Rails application receives an incoming HTTP request, say
+When your Rails application receives an incoming request
-<pre>
+<plain>
 GET /patients/17
-</pre>
-the routing engine within Rails is the piece of code that dispatches the request to the appropriate spot in your application. In this case, the application would most likely end up running the +show+ action within the +patients+ controller, displaying the details of the patient whose ID is 17.
-h4. Generating URLs from Code
-Routing also works in reverse. If your application contains this code:
-<ruby>
-@patient = Patient.find(17)
-</ruby>
-<erb>
-<%= link_to "Patient Record", patient_path(@patient) %>
-</erb>
-Then the routing engine is the piece that translates that to a link to a URL such as +http://example.com/patients/17+. By using routing in this way, you can reduce the brittleness of your application as compared to one with hard-coded URLs, and make your code easier to read and understand.
-NOTE: Patient needs to be declared as a Restful resource for this style of translation to be available.
-h3. Quick Tour of +routes.rb+
-There are two components to routing in Rails: the routing engine itself, which is supplied as part of Rails, and the file +config/routes.rb+, which contains the actual routes that will be used by your application. Learning exactly what you can put in +routes.rb+ is the main topic of this guide, but before we dig in let's get a quick overview.
-h4. Processing the File
-In format, +routes.rb+ is nothing more than one big block sent to +ApplicationName::Application.routes.draw+. Within this block, you can have comments, but it's likely that most of your content will be individual lines of code - each line being a route in your application. You'll find five main types of content in this file:
-* RESTful Routes
-* Named Routes
-* Nested Routes
-* Regular Routes
-* Default Routes
+</plain>
-Each of these types of route is covered in more detail later in this guide.
-The +routes.rb+ file is processed from top to bottom when a request comes in. The request will be dispatched to the first matching route, and then proceeds to the next. If there is no matching route, then Rails returns HTTP status 404 to the caller.
-h4. RESTful Routes
-RESTful routes take advantage of the built-in REST orientation of Rails to wrap up a lot of routing information with a single declaration. A RESTful route looks like this:
+it asks the router to match it to a controller action. If the first matching route is
 <ruby>
-resources :books
+match "/patients/:id" => "patients#show"
 </ruby>
-h4. Named Routes
-Named routes give you very readable links in your code, as well as handling incoming requests. Here's a typical named route:
+the request is dispatched to the +patients+ controller's +show+ action with <tt>{ :id => "17" }</tt> in +params+.
-<ruby>
-match 'login' => 'sessions#new', :as => 'login'
-</ruby>
+h4. Generating URLs from Code
-If you're coming from Rails 2, this route will be equivalent to:
+You can also generate routes. If your application contains this code:
 <ruby>
-map.login '/login', :controller => 'sessions', :action => 'new'
+@patient = Patient.find(17)
 </ruby>
-You will also notice that +sessions#new+ is a shorthand for +:controller => 'sessions', :action => 'new'+. By declaring a named route such as this, you can use +login_path+ or +login_url+ in your controllers and views to generate the URLs for this route.
+<erb>
+<%= link_to "Patient Record", patients_path(@patient.id) %>
+</erb>
-h4. Nested Routes
+The router will generate the path +/patients/17+. This reduces the brittleness of your view and makes your code easier to understand.
-Nested routes let you declare that one resource is contained within another resource. You'll see later on how this translates to URLs and paths in your code. For example, if your application includes parts, each of which belongs to an assembly, you might have this nested route declaration:
+h3. Resource Routing: the Rails Default
-<ruby>
-resources :assemblies do
-  resources :parts
-end
-</ruby>
+Resource routing allows you to quickly declare all of the common routes for a given resourceful controller. Instead of declaring separate routes for your +index+, +show+, +new+, +edit+, +create+, +update+ and +destroy+ actions, a resourceful route declares them in a single line of code.
-h4. Regular Routes
+h4. Resources on the Web
-In many applications, you'll also see non-RESTful routing, which explicitly connects the parts of a URL to a particular action. For example,
+Browsers request pages from Rails by making a request for a URL using a specific HTTP method, such as +GET+, +POST+, +PUT+ and +DELETE+. Each method is a request to perform an operation on the resource. A resource route maps a number of related request to the actions in a single controller.
-<ruby>
-match 'parts/:number' => 'inventory#show'
-</ruby>
+When your Rails application receives an incoming request for
-h4. Default Routes
+<plain>
+DELETE /photos/17
+</plain>
-The default route is a safety net that catches otherwise-unrouted requests. Many Rails applications will contain this default route:
+it asks the router to map it to a controller action. If the first matching route is
 <ruby>
-match ':controller(/:action(/:id(.:format)))'
+resources :photos
 </ruby>
-In Rails 3, this route is commented out advising to use RESTful routes as much as possible. So if you're using RESTful routing for everything in your application, you will probably want to leave it like that.
-h3. RESTful Routing: the Rails Default
-RESTful routing is the current standard for routing in Rails, and it's the one that you should prefer for new applications. It can take a little while to understand how RESTful routing works, but it's worth the effort; your code will be easier to read and you'll be working with Rails, rather than fighting against it, when you use this style of routing.
-h4. What is REST?
-The foundation of RESTful routing is generally considered to be Roy Fielding's doctoral thesis, "Architectural Styles and the Design of Network-based Software Architectures":http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm. Fortunately, you need not read this entire document to understand how REST works in Rails. REST, an acronym for Representational State Transfer, boils down to two main principles for our purposes:
-* Using resource identifiers (which, for the purposes of discussion, you can think of as URLs) to represent resources
-* Transferring representations of the state of that resource between system components.
-For example, to a Rails application a request such as this:
-<pre>
-DELETE /photos/17
-</pre>
-would be understood to refer to a photo resource with the ID of 17, and to indicate a desired action - deleting that resource. REST is a natural style for the architecture of web applications, and Rails makes it even more natural by using conventions to shield you from some of the RESTful complexities.
+Rails would dispatch that request to the +destroy+ method on the +photos+ controller with <tt>{ :id => "17" }</tt> in +params+.
 h4. CRUD, Verbs, and Actions
-In Rails, a RESTful route provides a mapping between HTTP verbs, controller actions, and (implicitly) CRUD operations in a database. A single entry in the routing file, such as
+In Rails, a resourceful route provides a mapping between HTTP verbs and URLs and controller actions. By convention, each action also maps to particular CRUD operations in a database. A single entry in the routing file, such as
 <ruby>
 resources :photos
 </ruby>
-creates seven different routes in your application:
-|_.HTTP verb|_.URL           |_.controller|_.action |_.used for|
-|GET        |/photos         |Photos      |index    |display a list of all photos|
-|GET        |/photos/new     |Photos      |new      |return an HTML form for creating a new photo|
-|POST       |/photos         |Photos      |create   |create a new photo|
-|GET        |/photos/1       |Photos      |show     |display a specific photo|
-|GET        |/photos/1/edit  |Photos      |edit     |return an HTML form for editing a photo|
-|PUT        |/photos/1       |Photos      |update   |update a specific photo|
-|DELETE     |/photos/1       |Photos      |destroy  |delete a specific photo|
+creates seven different routes in your application, all mapping to the +Photos+ controller:
-For the specific routes (those that reference just a single resource), the identifier for the resource will be available within the corresponding controller action as +params[:id]+.
+|_. Verb |_.URL             |_.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|
+|GET     |/photos/:id       |show     |display a specific photo|
+|GET     |/photos/:id/edit  |edit     |return an HTML form for editing a photo|
+|PUT     |/photos/:id       |update   |update a specific photo|
+|DELETE  |/photos/:id       |destroy  |delete a specific photo|
 h4. URLs and Paths
-Creating a RESTful route will also make available a pile of helpers within your application, something that requires explicit mention otherwise:
+Creating a resourceful route will also expose a number of helpers to the controllers in your application. In the case of +resources :photos+:
-* +photos_url+ and +photos_path+ map to the path for the index and create actions
-* +new_photo_url+ and +new_photo_path+ map to the path for the new action
-* +edit_photo_url+ and +edit_photo_path+ map to the path for the edit action
-* +photo_url+ and +photo_path+ map to the path for the show, update, and destroy actions
+* +photos_path+ returns +/photos+
+* +new_photo_path+ returns +/photos/new+
+* +edit_photo_path+ returns +/photos/edit+
+* +photo_path(id)+ returns +/photos/:id+ (for instance, +photo_path(10)+ returns +/photos/10+)
-NOTE: Because routing makes use of the HTTP verb as well as the path in the request to dispatch requests, the seven routes generated by a RESTful routing entry only give rise to four pairs of helpers.
+Each of these helpers has a corresponding +_url+ helper (such as +photos_url+) which returns the same path prefixed with the current host, port and path prefix.
-In each case, the +_url+ helper generates a string containing the entire URL that the application will understand, while the +_path+ helper generates a string containing the relative path from the root of the application. For example:
-<ruby>
-photos_url  # => "http://www.example.com/photos"
-photos_path # => "/photos"
-</ruby>
+NOTE: Because the router uses the HTTP verb and URL to match inbound requests, four URLs map to seven different actions.
 h4. Defining Multiple Resources at the Same Time
-If you need to create routes for more than one RESTful resource, you can save a bit of typing by defining them all with a single call to +resources+:
+If you need to create routes for more than one resource, you can save a bit of typing by defining them all with a single call to +resources+:
 <ruby>
 resources :photos, :books, :videos
 </ruby>
-This has exactly the same effect as
+This works exactly the same as
 <ruby>
 resources :photos
@@ -185,659 +116,615 @@ resources :videos
 h4. Singular Resources
-You can also apply RESTful routing to singleton resources within your application. In this case, you use +resource+ instead of +resources+ and the route generation is slightly different. For example, a routing entry of
+Sometimes, you have a resource that clients always look up without referencing an ID. A common example, +/profile+ always shows the profile of the currently logged in user. In this case, you can use a singular resource to map +/profile+ (rather than +/profile/:id+) to the +show+ action.
 <ruby>
 resource :geocoder
 </ruby>
-creates six different routes in your application:
-|_.HTTP verb|_.URL           |_.controller|_.action |_.used for|
-|GET        |/geocoder/new   |Geocoders   |new      |return an HTML form for creating the new geocoder|
-|POST       |/geocoder       |Geocoders   |create   |create the new geocoder|
-|GET        |/geocoder       |Geocoders   |show     |display the one and only geocoder resource|
-|GET        |/geocoder/edit  |Geocoders   |edit     |return an HTML form for editing the geocoder|
-|PUT        |/geocoder       |Geocoders   |update   |update the one and only geocoder resource|
-|DELETE     |/geocoder       |Geocoders   |destroy  |delete the geocoder resource|
-NOTE: Even though the name of the resource is singular in +routes.rb+, the matching controller is still plural.
+creates six different routes in your application, all mapping to the +Geocoders+ controller:
-A singular RESTful route generates an abbreviated set of helpers:
+|_. Verb    |_.URL          |_.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|
+|GET        |/geocoder/edit |edit     |return an HTML form for editing the geocoder|
+|PUT        |/geocoder      |update   |update the one and only geocoder resource|
+|DELETE     |/geocoder      |destroy  |delete the geocoder resource|
-* +new_geocoder_url+ and +new_geocoder_path+ map to the path for the new action
-* +edit_geocoder_url+ and +edit_geocoder_path+ map to the path for the edit action
-* +geocoder_url+ and +geocoder_path+ map to the path for the create, show, update, and destroy actions
+NOTE: Because you might want to use the same controller for a singular route (+/account+) and a plural route (+/accounts/45+), singular resources map to plural controllers.
-h4. Customizing Resources
+A singular resourceful route generates these helpers:
-Although the conventions of RESTful routing are likely to be sufficient for many applications, there are a number of ways to customize the way that RESTful routes work. These options include:
+* +new_geocoder_path+ returns +/geocoder/new+
+* +edit_geocoder_path+ returns +/geocoder/edit+
+* +geocoder_path+ returns +/geocoder+
-* +:controller+
-* +:singular+
-* +:requirements+
-* +:conditions+
-* +:as+
-* +:path_names+
-* +:only+
-* +:except+
+As with plural resources, the same helpers ending in +_url+ will also include the host, port and path prefix.
-You can also add additional routes via the +member+ and +collection+ blocks, which are discussed later in this guide.
-h5. Using +:controller+
+h4. Controller Namespaces and Routing
-The +:controller+ option lets you use a controller name that is different from the public-facing resource name. For example, this routing entry:
+You may wish to organize groups of controllers under a namespace. Most commonly, you might group a number of administrative controllers under an +Admin::+ namespace. You would place these controllers under the +app/controllers/admin+ directory, and you can group them together in your router:
 <ruby>
-resources :photos, :controller => "images"
+namespace "admin" do
+  resources :posts, :comments
+end
 </ruby>
-will recognize incoming URLs containing +photo+ but route the requests to the Images controller:
+This will create a number of routes for each of the +posts+ and +comments+ controller. For +Admin::PostsController+, Rails will create:
-|_.HTTP verb|_.URL           |_.controller|_.action |_.used for|
-|GET        |/photos         |Images      |index    |display a list of all images|
-|GET        |/photos/new     |Images      |new      |return an HTML form for creating a new image|
-|POST       |/photos         |Images      |create   |create a new image|
-|GET        |/photos/1       |Images      |show     |display a specific image|
-|GET        |/photos/1/edit  |Images      |edit     |return an HTML form for editing an image|
-|PUT        |/photos/1       |Images      |update   |update a specific image|
-|DELETE     |/photos/1       |Images      |destroy  |delete a specific image|
+|_. Verb |_.URL                |_.action |_. helper                  |
+|GET     |/admin/photos        |index    | admin_photos_path         |
+|GET     |/admin/photos/new    |new      | new_admin_photos_path     |
+|POST    |/admin/photos        |create   | admin_photos_path         |
+|GET     |/admin/photos/1      |show     | admin_photo_path(id)      |
+|GET     |/admin/photos/1/edit |edit     | edit_admin_photo_path(id) |
+|PUT     |/admin/photos/1      |update   | admin_photo_path(id)      |
+|DELETE  |/admin/photos/1      |destroy  | admin_photo_path(id)      |
-NOTE: The helpers will be generated with the name of the resource, not the name of the controller. So in this case, you'd still get +photos_path+, +new_photo_path+, and so on.
-h4. Controller Namespaces and Routing
-Rails allows you to group your controllers into namespaces by saving them in folders underneath +app/controllers+. The +:controller+ option provides a convenient way to use these routes. For example, you might have a resource whose controller is purely for admin users in the +admin+ folder:
+If you want to route +/photos+ (without the prefix +/admin+) to +Admin::PostsController+, you could use
 <ruby>
-resources :photos, :controller => "admin/photos"
+scope :module => "admin" do
+  resources :posts, :comments
+end
 </ruby>
-If you use controller namespaces, you need to be aware of a subtlety in the Rails routing code: it always tries to preserve as much of the namespace from the previous request as possible. For example, if you are on a view generated from the +photo_path+ helper, and you follow a link generated with +&lt;%= link_to "show", photo_path(1) %&gt;+ you will end up on the view generated by +admin/photos/show+, but you will also end up in the same place if you have +&lt;%= link_to "show", {:controller => "photos", :action => "show"} %&gt;+ because Rails will generate the show URL relative to the current URL.
-TIP: If you want to guarantee that a link goes to a top-level controller, use a preceding slash to anchor the controller name: +&lt;%= link_to "show", {:controller => "/photos", :action => "show"} %&gt;+
-You can also specify a controller namespace with the +:namespace+ option instead of a path:
+or, for a single case
 <ruby>
-resources :adminphotos, :namespace => "admin", :controller => "photos"
+resources :posts, :module => "admin"
 </ruby>
-This can be especially useful when map multiple namespaced routes together using +namespace+ block by:
+If you want to route +/admin/photos+ to +PostsController+ (without the +Admin::+ module prefix), you could use
 <ruby>
-namespace :admin do
-  resources :photos, :videos
+scope "/admin" do
+  resources :posts, :comments
 end
 </ruby>
-That would give you routing for +admin/photos+ and +admin/videos+ controllers.
-The difference between generating routes through +namespace+ and the +:controller+ key is that the +namespace+ will add +admin+ to the generated helpers as well, so the above route generates +admin_photos_path+.
-h5. Using +:singular+
-If for some reason Rails isn't doing what you want in converting the plural resource name to a singular name in member routes, you can override its judgment with the +:singular+ option:
+or, for a single case
 <ruby>
-resources :teeth, :singular => "tooth"
+resources :posts, :path => "/admin"
 </ruby>
-TIP: Depending on the other code in your application, you may prefer to add additional rules to the +Inflector+ class instead.
-h5. Using +:requirements+
+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+:
-You can use the +:requirements+ option in a RESTful route to impose a format on the implied +:id+ parameter in the singular routes. For example:
+|_. Verb |_.URL         |_.action |_. helper            |
+|GET     |photos        |index    | photos_path         |
+|GET     |photos/new    |new      | photos_path         |
+|POST    |photos        |create   | photos_path         |
+|GET     |photos/1      |show     | photo_path(id)      |
+|GET     |photos/1/edit |edit     | dmin_photo_path(id) |
+|PUT     |photos/1      |update   | photo_path(id)      |
+|DELETE  |photos/1      |destroy  | photo_path(id)      |
-<ruby>
-resources :photos, :requirements => {:id => /[A-Z][A-Z][0-9]+/}
-</ruby>
-This declaration constrains the +:id+ parameter to match the supplied regular expression. So, in this case, +/photos/1+ would no longer be recognized by this route, but +/photos/RR27+ would.
+h4. Nested Resources
-h5. Using +:conditions+
+It's common to have resources that are logically children of other resources. For example, suppose your application includes these models:
-Conditions in Rails routing are currently used only to set the HTTP verb for individual routes. Although in theory you can set this for RESTful routes, in practice there is no good reason to do so. (You'll learn more about conditions in the discussion of classic routing later in this guide.)
+<ruby>
+class Magazine < ActiveRecord::Base
+  has_many :ads
+end
-h5. Using +:as+
+class Ad < ActiveRecord::Base
+  belongs_to :magazine
+end
+</ruby>
-The +:as+ option lets you override the normal naming for the actual generated paths. For example:
+Nested routes allow you to capture this relationship in your routing. In this case, you could include this route declaration:
 <ruby>
-resources :photos, :as => "images"
+resources :magazines do
+  resources :ads
+end
 </ruby>
-will recognize incoming URLs containing +image+ but route the requests to the Photos controller:
+In addition to the routes for magazines, this declaration will also route ads to an +AdsController+. The ad URLs require a magazine:
-|_.HTTP verb|_.URL           |_.controller|_.action |_:used for|
-|GET        |/images         |Photos      |index    |display a list of all photos|
-|GET        |/images/new     |Photos      |new      |return an HTML form for creating a new photo|
-|POST       |/images         |Photos      |create   |create a new photo|
-|GET        |/images/1       |Photos      |show     |display a specific photo|
-|GET        |/images/1/edit  |Photos      |edit     |return an HTML form for editing a photo|
-|PUT        |/images/1       |Photos      |update   |update a specific photo|
-|DELETE     |/images/1       |Photos      |destroy  |delete a specific photo|
+|_.Verb |_.URL                    |_.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|
+|GET    |/magazines/1/ads/1       |show     |display a specific ad belonging to a specific magazine|
+|GET    |/magazines/1/ads/1/edit  |edit     |return an HTML form for editing an ad belonging to a specific magazine|
+|PUT    |/magazines/1/ads/1       |update   |update a specific ad belonging to a specific magazine|
+|DELETE |/magazines/1/ads/1       |destroy  |delete a specific ad belonging to a specific magazine|
-NOTE: The helpers will be generated with the name of the resource, not the path name. So in this case, you'd still get +photos_path+, +new_photo_path+, and so on.
-h5. Using +:path_names+
+This will also create routing helpers such as +magazine_ads_url+ and +edit_magazine_ad_path+. These helpers take an instance of Magazine as the first parameter (+magazine_ads_url(@magazine)+).
-The +:path_names+ option lets you override the automatically-generated "new" and "edit" segments in URLs:
+h5. Limits to Nesting
+You can nest resources within other nested resources if you like. For example:
 <ruby>
-resources :photos, :path_names => { :new => 'make', :edit => 'change' }
+resources :publishers do
+  resources :magazines do
+    resources :photos
+  end
+end
 </ruby>
-This would cause the routing to recognize URLs such as
+Deeply-nested resources quickly become cumbersome. In this case, for example, the application would recognize URLs such as
 <pre>
-/photos/make
-/photos/1/change
+/publishers/1/magazines/2/photos/3
 </pre>
-NOTE: The actual action names aren't changed by this option; the two URLs shown would still route to the new and edit actions.
-TIP: If you find yourself wanting to change this option uniformly for all of your routes, you can set a default in your environment:
+The corresponding route helper would be +publisher_magazine_photo_url+, requiring you to specify objects at all three levels. Indeed, this situation is confusing enough that a popular "article":http://weblog.jamisbuck.org/2007/2/5/nesting-resources by Jamis Buck proposes a rule of thumb for good Rails design:
-<ruby>
-config.action_controller.resources_path_names = { :new => 'make', :edit => 'change' }
-</ruby>
+TIP: _Resources should never be nested more than 1 level deep._
-h5. Using +:path_prefix+
+h4. Creating URLs From Objects
-The +:path_prefix+ option lets you add additional parameters that will be prefixed to the recognized paths. For example, suppose each photo in your application belongs to a particular photographer. In that case, you might declare this route:
+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:
 <ruby>
-resources :photos, :path_prefix => '/photographers/:photographer_id'
+resources :magazines do
+  resources :ads
+end
 </ruby>
-Routes recognized by this entry would include:
+When using +magazine_ad_path+, you can pass in instances of +Magazine+ and +Ad+ instead of the numeric IDs.
-<pre>
-/photographers/1/photos/2
-/photographers/1/photos
-</pre>
-NOTE: In most cases, it's simpler to recognize URLs of this sort by creating nested resources, as discussed in the next section.
+<erb>
+<%= link_to "Ad details", magazine_ad_path(@magazine, @ad) %>
+</erb>
-NOTE: You can also use +:path_prefix+ with non-RESTful routes.
+You can also use +url_for+ with a set of objects, and Rails will automatically determine which route you want:
-h5. Using +:name_prefix+
+<erb>
+<%= link_to "Ad details", url_for(@magazine, @ad) %>
+</erb>
-You can use the :name_prefix option to avoid collisions between routes. This is most useful when you have two resources with the same name that use +:path_prefix+ to map differently. For example:
+In this case, Rails will see that +@magazine+ is a +Magazine+ and +@ad+ is an +Ad+ and will therefore use the +magazine_ad_path+ helper. In helpers like +link_to+, you can specify just the object in place of the full +url_for+ call:
-<ruby>
-resources :photos, :path_prefix => '/photographers/:photographer_id',
-  :name_prefix => 'photographer_'
-resources :photos, :path_prefix => '/agencies/:agency_id',
-  :name_prefix => 'agency_'
-</ruby>
+<erb>
+<%= link_to "Ad details", [@magazine, @ad] %>
+</erb>
-This combination will give you route helpers such as +photographer_photos_path+ and +agency_edit_photo_path+ to use in your code.
+If you wanted to link to just a magazine, you could leave out the +Array+:
-NOTE: You can also use +:name_prefix+ with non-RESTful routes.
+<erb>
+<%= link_to "Magazine details", @magazine %>
+</erb>
-h5. Using +:only+ and +:except+
+This allows you to treat instances of your models as URLs, and is a key advantage to using the resourceful style.
-By default, Rails creates routes for all seven of the default actions (index, show, new, create, edit, update, and destroy) for every RESTful route in your application. You can use the +:only+ and +:except+ options to fine-tune this behavior. The +:only+ option specifies that only certain routes should be generated:
+h4. Adding More RESTful Actions
-<ruby>
-resources :photos, :only => [:index, :show]
-</ruby>
+You are not limited to the seven routes that RESTful routing creates by default. If you like, you may add additional routes that apply to the collection or individual members of the collection.
-With this declaration, a +GET+ request to +/photos+ would succeed, but a +POST+ request to +/photos+ (which would ordinarily be routed to the create action) will fail.
+h5. Adding Member Routes
-The +:except+ option specifies a route or list of routes that should _not_ be generated:
+To add a member route, just add +member+ block into resource block:
 <ruby>
-resources :photos, :except => :destroy
+resources :photos do
+  member do
+    get :preview
+  end
+end
 </ruby>
-In this case, all of the normal routes except the route for +destroy+ (a +DELETE+ request to +/photos/<em>id</em>+) will be generated.
+This will recognize +/photos/1/preview+ with GET, and route to the +preview+ action of  +PhotosController+. It will also create the +preview_photo_url+ and +preview_photo_path+  helpers.
-In addition to an action or a list of actions, you can also supply the special symbols +:all+ or +:none+ to the +:only+ and +:except+ options.
+Within the block of member routes, each route name specifies the HTTP verb that it will recognize. You can use +get+, +put+, +post+, or +delete+ here. If you don't have multiple +member+ routes, you can also passing +:on+ to a route.
-TIP: If your application has many RESTful routes, using +:only+ and +:except+ to generate only the routes that you actually need can cut down on memory use and speed up the routing process.
+<ruby>
+resources :photos do
+  get :preview, :on => :member
+end
+</ruby>
-h4. Nested Resources
+h5. Adding Collection Routes
-It's common to have resources that are logically children of other resources. For example, suppose your application includes these models:
+To add a route to the collection:
 <ruby>
-class Magazine < ActiveRecord::Base
-  has_many :ads
-end
-class Ad < ActiveRecord::Base
-  belongs_to :magazine
+resources :photos do
+  collection do
+    get :search
+  end
 end
 </ruby>
-Each ad is logically subservient to one magazine. Nested routes allow you to capture this relationship in your routing. In this case, you might include this route declaration:
+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.
+Just as with member routes, you can pass +:on+ to a route.
 <ruby>
-resources :magazines do
-  resources :ads
+resources :photos do
+  get :search, :on => :collection
 end
 </ruby>
-TIP: Further below you'll learn about a convenient shortcut for this construct:<br/>+resources :magazines, :has_many => :ads+
-In addition to the routes for magazines, this declaration will also create routes for ads, each of which requires the specification of a magazine in the URL:
+h5. A Note of Caution
-|_.HTTP verb|_.URL                    |_.controller|_.action |_.used for|
-|GET        |/magazines/1/ads         |Ads         |index    |display a list of all ads for a specific magazine|
-|GET        |/magazines/1/ads/new     |Ads         |new      |return an HTML form for creating a new ad belonging to a specific magazine|
-|POST       |/magazines/1/ads         |Ads         |create   |create a new ad belonging to a specific magazine|
-|GET        |/magazines/1/ads/1       |Ads         |show     |display a specific ad belonging to a specific magazine|
-|GET        |/magazines/1/ads/1/edit  |Ads         |edit     |return an HTML form for editing an ad belonging to a specific magazine|
-|PUT        |/magazines/1/ads/1       |Ads         |update   |update a specific ad belonging to a specific magazine|
-|DELETE     |/magazines/1/ads/1       |Ads         |destroy  |delete a specific ad belonging to a specific magazine|
+If you find yourself adding many extra actions to a resourceful route, it's time to stop and ask yourself whether you're disguising the presence of another resource.
+h3. Non-Resourceful Routes
-This will also create routing helpers such as +magazine_ads_url+ and +edit_magazine_ad_path+.
+In addition to resource routing, Rails has powerful support for routing arbitrary URLs to actions. Here, you don't get groups of routes automatically generated by resourceful routing. Instead, you set up each route within your application separately.
-h5. Using +:name_prefix+
+While you should usually use resourceful routing, there are still many places where the simpler routing is more appropriate. There's no need to try to shoehorn every last piece of your application into a resourceful framework if that's not a good fit.
-The +:name_prefix+ option overrides the automatically-generated prefix in nested route helpers. For example,
+In particular, simple routing makes it very easy to map legacy URLs to new Rails actions.
-<ruby>
-resources :magazines do
-  resources :ads, :name_prefix => 'periodical'
-end
-</ruby>
+h4. Bound Parameters
-This will create routing helpers such as +periodical_ads_url+ and +periodical_edit_ad_path+. You can even use +:name_prefix+ to suppress the prefix entirely:
+When you set up a regular route, you supply a series of symbols that Rails maps to parts of an incoming HTTP request. Two of these symbols are special: +:controller+ maps to the name of a controller in your application, and +:action+ maps to the name of an action within that controller. For example, consider one of the default Rails routes:
 <ruby>
-resources :magazines do
-  resources :ads, :name_prefix => nil
-end
+match ':controller(/:action(/:id))'
 </ruby>
-This will create routing helpers such as +ads_url+ and +edit_ad_path+. Note that calling these will still require supplying an article id:
+If an incoming request of +/photos/show/1+ is processed by this route (because it hasn't matched any previous route in the file), then the result will be to invoke the +show+ action of the +PhotosController+, and to make the final parameter +"1"+ available as +params[:id]+. This route will also route the incoming request of +/photos+ to +PhotosController+, since +:action+ and +:id+ are optional parameters, denoted by parentheses.
-<ruby>
-ads_url(@magazine)
-edit_ad_path(@magazine, @ad)
-</ruby>
-h5. Using +:has_one+ and +:has_many+
+h4. Dynamic Segments
-The +:has_one+ and +:has_many+ options provide a succinct notation for simple nested routes. Use +:has_one+ to nest a singleton resource, or +:has_many+ to nest a plural resource:
+You can set up as many dynamic segments within a regular route as you like. Anything other than +:controller+ or +:action+ will be available to the action as part of +params+. If you set up this route:
 <ruby>
-resources :photos, :has_one => :photographer, :has_many => [:publications, :versions]
+match ':controller/:action/:id/:user_id'
 </ruby>
-This has the same effect as this set of declarations:
+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"+.
-<ruby>
-resources :photos do
-  resource :photographer
-  resources :publications
-  resources :versions
-end
-</ruby>
-h5. Limits to Nesting
+h4. Static Segments
-You can nest resources within other nested resources if you like. For example:
+You can specify static segments when creating a route.
 <ruby>
-resources :publishers do
-  resources :magazines do
-    resources :photos
-  end
-end
+match ':controller/:action/:id/with_user/:user_id'
 </ruby>
-However, without the use of +name_prefix => nil+, deeply-nested resources quickly become cumbersome. In this case, for example, the application would recognize URLs such as
-<pre>
-/publishers/1/magazines/2/photos/3
-</pre>
-The corresponding route helper would be +publisher_magazine_photo_url+, requiring you to specify objects at all three levels. Indeed, this situation is confusing enough that a popular "article":http://weblog.jamisbuck.org/2007/2/5/nesting-resources by Jamis Buck proposes a rule of thumb for good Rails design:
-TIP: _Resources should never be nested more than 1 level deep._
+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>.
-h5. Shallow Nesting
+h4. The Query String
-The +:shallow+ option provides an elegant solution to the difficulties of deeply-nested routes. If you specify this option at any level of routing, then paths for nested resources which reference a specific member (that is, those with an +:id+ parameter) will not use the parent path prefix or name prefix. To see what this means, consider this set of routes:
+The +params+ will also include any parameters from the query string. For example, with this route:
 <ruby>
-resources :publishers, :shallow => true do
-  resources :magazines do
-    resources :photos
-  end
-end
+match ':controller/:action/:id
 </ruby>
-This will enable recognition of (among others) these routes:
+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>.
-<pre>
-/publishers/1           ==> publisher_path(1)
-/publishers/1/magazines ==> publisher_magazines_path(1)
-/magazines/2            ==> magazine_path(2)
-/magazines/2/photos     ==> magazines_photos_path(2)
-/photos/3               ==> photo_path(3)
-</pre>
+h4. Defining Defaults
-With shallow nesting, you need only supply enough information to uniquely identify the resource that you want to work with. If you like, you can combine shallow nesting with the +:has_one+ and +:has_many+ options:
+You do not need to explicitly use the +:controller+ and +:action+ symbols within a route. You can supply them as defaults:
 <ruby>
-resources :publishers, :has_many => { :magazines => :photos }, :shallow => true
+match 'photos/:id' => 'photos#show'
 </ruby>
-h4. Route Generation from Arrays
+With this route, Rails will match an incoming URL of +/photos/12+ to the +show+ action of  +PhotosController+.
-In addition to using the generated routing helpers, Rails can also generate RESTful routes from an array of parameters. For example, suppose you have a set of routes generated with these entries in routes.rb:
+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:
 <ruby>
-resources :magazines do
-  resources :ads
-end
+match 'photos/:id' => 'photos#show', :defaults => { :format => 'jpg' }
 </ruby>
-Rails will generate helpers such as magazine_ad_path that you can use in building links:
+Rails would match +photos/12+ to the +show+ action of +PhotosController+, and set +params[:format]+ to +"jpg"+.
-<ruby>
-<%= link_to "Ad details", magazine_ad_path(@magazine, @ad) %>
-</ruby>
+h4. Naming Routes
-Another way to refer to the same route is with an array of objects:
+You can specify a name for any route using the +:as+ option.
 <ruby>
-<%= link_to "Ad details", [@magazine, @ad] %>
+match 'logout' => 'sessions#destroy', :as => :logout
 </ruby>
-This format is especially useful when you might not know until runtime which of several types of object will be used in a particular link.
+This will create +logout_path+ and +logout_url+ as named helpers in your application. Calling +logout_path+ will return +/logout+
-h4. Namespaced Resources
+h4. Segment Constraints
-It's possible to do some quite complex things by combining +:path_prefix+ and +:name_prefix+. For example, you can use the combination of these two options to move administrative resources to their own folder in your application:
+You can use the +:constraints+ option to enforce a format for a dynamic segment:
 <ruby>
-resources :photos, :path_prefix => 'admin', :controller => 'admin/photos'
-resources :tags, :name_prefix => 'admin_photo_', :path_prefix => 'admin/photos/:photo_id', :controller => 'admin/photo_tags'
-resources :ratings, :name_prefix => 'admin_photo_', :path_prefix => 'admin/photos/:photo_id', :controller => 'admin/photo_ratings'
+match 'photo/:id' => 'photos#show', :constraints => { :id => /[A-Z]\d{5}/ }
 </ruby>
-The good news is that if you find yourself using this level of complexity, you can stop. Rails supports _namespaced resources_ to make placing resources in their own folder a snap. Here's the namespaced version of those same three routes:
+This route would match URLs such as +/photo/A12345+. You can more succinctly express the same route this way:
 <ruby>
-namespace :admin do
-	resources :photos, :has_many => { :tags, :ratings }
-end
+match 'photo/:id' => 'photos#show', :id => /[A-Z]\d{5}/
 </ruby>
-As you can see, the namespaced version is much more succinct than the one that spells everything out - but it still creates the same routes. For example, you'll get +admin_photos_url+ that expects to find an +Admin::PhotosController+ and that matches +admin/photos+, and +admin_photos_ratings_path+ that matches +/admin/photos/_photo_id_/ratings+, expecting to use +Admin::RatingsController+. Even though you're not specifying +path_prefix+ explicitly, the routing code will calculate the appropriate +path_prefix+ from the route nesting.
-h4. Adding More RESTful Actions
+h4. Request-Based Constraints
-You are not limited to the seven routes that RESTful routing creates by default. If you like, you may add additional member routes (those which apply to a single instance of the resource), additional new routes (those that apply to creating a new resource), or additional collection routes (those which apply to the collection of resources as a whole).
-h5. Adding Member Routes
+You can also constrain a route based on any method on the <a href="action_controller_overview.html#the-request-object">Request</a> object that returns a +String+.
-To add a member route, just add +member+ block into resource block:
+You specify a request-based constraint the same way that you specify a segment constraint:
 <ruby>
-resources :photos do
-  member do
-    get :preview
-  end
-end
+match "photo", :constraints => {:subdomain => "admin"}
 </ruby>
-This will enable Rails to recognize URLs such as +/photos/1/preview+ using the GET HTTP verb, and route them to the preview action of the Photos controller. It will also create the +preview_photo_url+ and +preview_photo_path+ route helpers.
-Within the block of member routes, each route name specifies the HTTP verb that it will recognize. You can use +get+, +put+, +post+, +delete+, or +any+ here. If you don't have multiple +member+ route, you can also passing +:on+ to the routing.
+You can also specify constrains in a block form:
 <ruby>
-resources :photos do
-  get :preview, :on => :member
+namespace "admin" do
+  constraints :subdomain => "admin" do
+    resources :photos
+  end
 end
 </ruby>
-h5. Adding Collection Routes
+h4. Advanced Constraints
-To add a collection route, use the +:collection+ option:
+If you have a more advanced constraint, you can provide an object that responds to +matches?+ that Rails should use. Let's say you wanted to route all users on a blacklist to the +BlacklistController+. You could do:
 <ruby>
-resources :photos do
-  collection do
-    get :search
+class BlacklistConstraint
+  def initialize
+    @ips = Blacklist.retrieve_ips
   end
-end
-</ruby>
-This will enable Rails to recognize URLs such as +/photos/search+ using the GET HTTP verb, and route them to the search action of the Photos controller. It will also create the +search_photos_url+ and +search_photos_path+ route helpers.
-Just as with member routes, you can passing +:on+ to the routing.
+  def matches?(request)
+    @ips.include?(request.remote_ip)
+  end
+end
-<ruby>
-resources :photos do
-  get :search, :on => :collection
+TwitterClone::Application.routes.draw do
+  match "*path" => "blacklist#index",
+    :constraints => BlacklistConstraint.new
 end
 </ruby>
-h5. Adding New Routes
+h4. Route Globbing
-As of writing, Rails 3 has deprecated +:new+ option from routing. You will need to explicit define the route using +match+ method
+Route globbing is a way to specify that a particular parameter should be matched to all the remaining parts of a route. For example
 <ruby>
-resources :photos
-match 'photos/new/upload' => 'photos#upload', :as => 'upload_new_photos'
+match 'photo/*other' => 'photos#unknown'
 </ruby>
-h5. A Note of Caution
+This route would match +photo/12+ or +/photo/long/path/to/12+, setting +params[:other]+ to +"12"+ or +"long/path/to/12"+.
-If you find yourself adding many extra actions to a RESTful route, it's time to stop and ask yourself whether you're disguising the presence of another resource that would be better split off on its own. When the +member+ and +collection+ hashes become a dumping-ground, RESTful routes lose the advantage of easy readability that is one of their strongest points.
+h4. Redirection
-h3. Regular Routes
+You can redirect any path to another path using the +redirect+ helper in your router:
-In addition to RESTful routing, Rails supports regular routing - a way to map URLs to controllers and actions. With regular routing, you don't get the masses of routes automatically generated by RESTful routing. Instead, you must set up each route within your application separately.
+<ruby>
+match "/stories" => redirect("/posts")
+</ruby>
-While RESTful routing has become the Rails standard, there are still plenty of places where the simpler regular routing works fine. You can even mix the two styles within a single application. In general, you should prefer RESTful routing _when possible_, because it will make parts of your application easier to write. But there's no need to try to shoehorn every last piece of your application into a RESTful framework if that's not a good fit.
+You can also reuse dynamic segments from the match in the path to redirect to:
-h4. Bound Parameters
+<ruby>
+match "/stories/:name" => redirect("/posts/%{name}")
+</ruby>
-When you set up a regular route, you supply a series of symbols that Rails maps to parts of an incoming HTTP request. Two of these symbols are special: +:controller+ maps to the name of a controller in your application, and +:action+ maps to the name of an action within that controller. For example, consider one of the default Rails routes:
+You can also provide a block to redirect, which receives the params and (optionally) the request object:
 <ruby>
-match ':controller(/:action(/:id))'
+match "/stories/:name" => redirect {|params| "/posts/#{params[:name].pluralize}" }
+match "/stories" => redirect {|p, req| "/posts/#{req.subdomain}" }
 </ruby>
-If an incoming request of +/photos/show/1+ is processed by this route (because it hasn't matched any previous route in the file), then the result will be to invoke the +show+ action of the +Photos+ controller, and to make the final parameter (1) available as +params[:id]+.
+In all of these cases, if you don't provide the leading host (+http://www.example.com+), Rails will take those details from the current request.
-h4. Wildcard Components
+h4. Routing to Rack Applications
-You can set up as many wildcard symbols within a regular route as you like. Anything other than +:controller+ or +:action+ will be available to the matching action as part of the params hash. So, if you set up this route:
+Instead of a String, like +"posts#index"+, which corresponds to the +index+ action in the +PostsController+, you can specify any <a href="rails_on_rack.html">Rack application</a> as the endpoint for a matcher.
 <ruby>
-match ':controller/:action/:id/:user_id'
+match "/application.js" => Sprockets
 </ruby>
-An incoming URL of +/photos/show/1/2+ will be dispatched to the +show+ action of the +Photos+ controller. +params[:id]+ will be set to 1, and +params[:user_id]+ will be set to 2.
+As long as +Sprockets+ responds to +call+ and returns a <tt>[status, headers, body]</tt>, the router won't know the difference between the Rack application and an action.
-h4. Static Text
+NOTE: For the curious, +"posts#index"+ actually expands out to +PostsController.action(:index)+, which returns a valid Rack application.
-You can specify static text when creating a route. In this case, the static text is used only for matching the incoming requests:
+h4. Using +root+
+You can specify what Rails should route +"/"+ to with the +root+ method:
 <ruby>
-match ':controller/:action/:id/with_user/:user_id'
+root :to => 'pages#main'
 </ruby>
-This route would respond to URLs such as +/photos/show/1/with_user/2+.
+You should put the +root+ route at the end of the file.
+h3. Customizing Resourceful Routes
+While the default routes and helpers generated by +resources :posts+ will usually serve you well, you may want to customize them in some way. Rails allows you to customize virtually any generic part of the resourceful helpers.
-h4. Querystring Parameters
+h4. Specifying a Controller to Use
-Rails routing automatically picks up querystring parameters and makes them available in the +params+ hash. For example, with this route:
+The +:controller+ option lets you explicitly specify a controller to use for the resource. For example:
 <ruby>
-match ':controller/:action/:id
+resources :photos, :controller => "images"
 </ruby>
-An incoming URL of +/photos/show/1?user_id=2+ will be dispatched to the +show+ action of the +Photos+ controller. +params[:id]+ will be set to 1, and +params[:user_id]+ will be equal to 2.
+will recognize incoming URLs beginning with +/photo+ but route to the +Images+ controller:
-h4. Defining Defaults
+|_. Verb |_.URL          |_.action |
+|GET     |/photos        |index    |
+|GET     |/photos/new    |new      |
+|POST    |/photos        |create   |
+|GET     |/photos/1      |show     |
+|GET     |/photos/1/edit |edit     |
+|PUT     |/photos/1      |update   |
+|DELETE  |/photos/1      |destroy  |
+NOTE: Use +photos_path+, +new_photos_path+, etc. to generate URLs for this resource.
+h4. Specifying Constraints
-You do not need to explicitly use the +:controller+ and +:action+ symbols within a route. You can supply defaults for these two parameters by putting it after +=>+:
+You can use the +:constraints+ option to specify a required format on the implicit +id+. For example:
 <ruby>
-match 'photos/:id' => 'photos#show'
+resources :photos, :constraints => {:id => /[A-Z][A-Z][0-9]+/}
 </ruby>
-With this route, an incoming URL of +/photos/12+ would be dispatched to the +show+ action within the +Photos+ controller.
+This declaration constrains the +:id+ parameter to match the supplied regular expression. So, in this case, the router would no longer match +/photos/1+ to this route. Instead, +/photos/RR27+ would match.
-You can also define other defaults in a route by supplying a hash for the +:defaults+ option. This even applies to parameters that are not explicitly defined elsewhere in the route. For example:
+You can specify a single constraint to a apply to a number of routes by using the block form:
 <ruby>
-match 'photos/:id' => 'photos#show', :defaults => { :format => 'jpg' }
+constraints(:id => /[A-Z][A-Z][0-9]+/) do
+  resources :photos
+  resources :accounts
+end
 </ruby>
-With this route, an incoming URL of +photos/12+ would be dispatched to the +show+ action within the +Photos+ controller, and +params[:format]+ will be set to +jpg+.
+NOTE: Of course, you can use the more advanced constraints available in non-resourceful routes in this context
-h4. Named Routes
+h4. Overriding the Named Helpers
-Regular routes need not use the +connect+ method. You can use any other name here to create a _named route_. For example,
+The +:as+ option lets you override the normal naming for the named route helpers. For example:
 <ruby>
-match 'logout' => 'sessions#destroy', :as => :logout
+resources :photos, :as => "images"
 </ruby>
-This will do two things. First, requests to +/logout+ will be sent to the +destroy+ action of the +Sessions+ controller. Second, Rails will maintain the +logout_path+ and +logout_url+ helpers for use within your code.
+will recognize incoming URLs beginning with +/photos+ and route the requests to +PhotosController+:
+|_.HTTP verb|_.URL           |_.action |_.named helper   |
+|GET        |/photos         |index    | images_path_    |
+|GET        |/photos/new     |new      | new_image_path  |
+|POST       |/photos         |create   | images_path     |
+|GET        |/photos/1       |show     | image_path      |
+|GET        |/photos/1/edit  |edit     | edit_image_path |
+|PUT        |/photos/1       |update   | image_path      |
+|DELETE     |/photos/1       |destroy  | image_path      |
-h4. Route Requirements
+h4. Overriding the +new+ and +edit+ Segments
-You can use the +:requirements+ option to enforce a format for any parameter in a route:
+The +:path_names+ option lets you override the automatically-generated "new" and "edit" segments in URLs:
 <ruby>
-match 'photo/:id' => 'photos#show', :requirements => { :id => /[A-Z]\d{5}/ }
+resources :photos, :path_names => { :new => 'make', :edit => 'change' }
 </ruby>
-This route would respond to URLs such as +/photo/A12345+. You can more succinctly express the same route this way:
+This would cause the routing to recognize URLs such as
-<ruby>
-match 'photo/:id' => 'photos#show', :id => /[A-Z]\d{5}/
-</ruby>
+<plain>
+/photos/make
+/photos/1/change
+</plain>
-h4. Route Conditions
+NOTE: The actual action names aren't changed by this option. The two URLs shown would still route to the new and edit actions.
-Route conditions (introduced with the +:conditions+ option) are designed to implement restrictions on routes. Currently, the only supported restriction is +:method+:
+TIP: If you find yourself wanting to change this option uniformly for all of your routes, you can use a scope:
 <ruby>
-match 'photo/:id' => 'photos#show', :conditions => { :method => :get }
+scope :path_names => { :new => "make" } do
+  # rest of your routes
+end
 </ruby>
-As with conditions in RESTful routes, you can specify +:get+, +:post+, +:put+, +:delete+, or +:any+ for the acceptable method.
-h4. Route Globbing
+h4. Overriding the Named Helper Prefix
-Route globbing is a way to specify that a particular parameter should be matched to all the remaining parts of a route. For example
+You can use the :name_prefix option to add a prefix to the named route helpers that Rails generates for a route. You can use this option to prevent collisions between routes using a path scope.
 <ruby>
-match 'photo/*other' => 'photos#unknown'
-</ruby>
+scope "admin" do
+  resources :photos, :name_prefix => "admin"
+end
-This route would match +photo/12+ or +/photo/long/path/to/12+ equally well, creating an array of path segments as the value of +params[:other]+.
+resources :photos
+</ruby>
-h4. Route Options
+This will provide route helpers such as +photographer_photos_path+.
-You can use +:with_options+ to simplify defining groups of similar routes:
+You could specify a name prefix to use for a group of routes in the scope:
 <ruby>
-map.with_options :controller => 'photo' do |photo|
-  photo.list '', :action => 'index'
-  photo.delete ':id/delete', :action => 'delete'
-  photo.edit ':id/edit', :action => 'edit'
+scope "admin", :name_prefix => "admin" do
+  resources :photos, :accounts
 end
-</ruby>
-The importance of +map.with_options+ has declined with the introduction of RESTful routes.
+resources :photos, :accounts
+</ruby>
-h3. Formats and +respond_to+
+NOTE: The +namespace+ scope will automatically add a +:name_prefix+ as well as +:module+ and +:path+ prefixes.
-There's one more way in which routing can do different things depending on differences in the incoming HTTP request: by issuing a response that corresponds to what the request specifies that it will accept. In Rails routing, you can control this with the special +:format+ parameter in the route.
+h4. Restricting the Routes Created
-For instance, consider the second of the default routes in the boilerplate +routes.rb+ file:
+By default, Rails creates routes for all seven of the default actions (index, show, new, create, edit, update, and destroy) for every RESTful route in your application. You can use the +:only+ and +:except+ options to fine-tune this behavior. The +:only+ option tells Rails to create only the specified routes:
 <ruby>
-match ':controller(/:action(/:id(.:format)))'
+resources :photos, :only => [:index, :show]
 </ruby>
-This route matches requests such as +/photo/edit/1.xml+ or +/photo/show/2.rss+. Within the appropriate action code, you can issue different responses depending on the requested format:
+Now, a +GET+ request to +/photos+ would succeed, but a +POST+ request to +/photos+ (which would ordinarily be routed to the +create+ action) will fail.
+The +:except+ option specifies a route or list of routes that Rails should _not_ create:
 <ruby>
-respond_to do |format|
-  format.html # return the default template for HTML
-  format.xml { render :xml => @photo.to_xml }
-end
+resources :photos, :except => :destroy
 </ruby>
-h4. Specifying the Format with an HTTP Header
-If there is no +:format+ parameter in the route, Rails will automatically look at the HTTP Accept header to determine the desired format.
-h4. Recognized MIME types
+In this case, Rails will create all of the normal routes except the route for +destroy+ (a +DELETE+ request to +/photos/:id+).
-By default, Rails recognizes +html+, +text+, +json+, +csv+, +xml+, +rss+, +atom+, and +yaml+ as acceptable response types. If you need types beyond this, you can register them in your environment:
-<ruby>
-Mime::Type.register "image/jpg", :jpg
-</ruby>
+TIP: If your application has many RESTful routes, using +:only+ and +:except+ to generate only the routes that you actually need can cut down on memory use and speed up the routing process.
-h3. The Default Routes
+h4. Translated Paths
-When you create a new Rails application, +routes.rb+ is initialized with a default route:
+Using +scope+, we can alter path names generated by resources:
 <ruby>
-match ':controller(/:action(/:id(.:format)))'
+scope(:path_names => { :new => "neu", :edit => "bearbeiten" }) do
+  resources :categories, :path => "kategorien"
+end
 </ruby>
-These routes provide reasonable defaults for many URLs, if you're not using RESTful routing.
+Rails now creates routes to the +CategoriesControlleR+.
-NOTE: The default routes will make every action of every controller in your application accessible to GET requests. If you've designed your application to make consistent use of RESTful and named routes, you should comment out the default routes to prevent access to your controllers through the wrong verbs. If you've had the default routes enabled during development, though, you need to be sure that you haven't unwittingly depended on them somewhere in your application - otherwise you may find mysterious failures when you disable them.
+|_.HTTP verb|_.URL                      |_.action |
+|GET        |/kategorien                |index    |
+|GET        |/kategorien/neu            |new      |
+|POST       |/kategorien                |create   |
+|GET        |/kategorien/1              |show     |
+|GET        |/kategorien/:id/bearbeiten |edit     |
+|PUT        |/kategorien/1              |update   |
+|DELETE     |/kategorien/1              |destroy  |
-h3. The Empty Route
+h4. Overriding the Singular Form
-Don't confuse the default routes with the empty route. The empty route has one specific purpose: to route requests that come in to the root of the web site. For example, if your site is example.com, then requests to +http://example.com+ or +http://example.com/+ will be handled by the empty route.
-h4. Using +root+
-The preferred way to set up the empty route is with the +root+ command:
+If you want to customize the singular name of the route in the named helpers, you can use the +:singular+ option.
 <ruby>
-root :to => 'pages#main'
+resources :teeth, :singular => "tooth"
 </ruby>
-The use of the +root+ method tells Rails that this route applies to requests for the root of the site.
+TIP: If you want to define the singular form of a word for your entire application, you should add additional rules to the +Inflector+ instead.
-Because of the top-down processing of the file, the named route must be specified _before_ the call to +root+.
+h4(#nested-name-prefix). Using +:name_prefix+ in Nested Resources
-h4. Connecting the Empty String
-You can also specify an empty route by explicitly connecting the empty string:
+The +:name_prefix+ option overrides the automatically-generated prefix for the parent resource in nested route helpers. For example,
 <ruby>
-match '' => 'pages#main'
+resources :magazines do
+  resources :ads, :name_prefix => 'periodical'
+end
 </ruby>
-TIP: If the empty route does not seem to be working in your application, make sure that you have deleted the file +public/index.html+ from your Rails tree.
+This will create routing helpers such as +periodical_ads_url+ and +periodical_edit_ad_path+.
 h3. Inspecting and Testing Routes
-Routing in your application should not be a "black box" that you never open. Rails offers built-in tools for both inspecting and testing routes.
+Rails offers facilities for inspecting and testing your routes.
 h4. Seeing Existing Routes with +rake+
-If you want a complete list of all of the available routes in your application, run the +rake routes+ command. This will dump all of your routes to the console, in the same order that they appear in +routes.rb+. For each route, you'll see:
+If you want a complete list of all of the available routes in your application, run +rake routes+ command. This will print all of your routes, in the same order that they appear in +routes.rb+. For each route, you'll see:
 * The route name (if any)
 * The HTTP verb used (if the route doesn't respond to all verbs)
-* The URL pattern
-* The routing parameters that will be generated by this URL
+* The URL pattern to match
+* The routing parameters for the route
 For example, here's a small section of the +rake routes+ output for a RESTful route:
@@ -881,7 +768,7 @@ You can supply a +:method+ argument to specify the HTTP verb:
 assert_recognizes({ :controller => "photos", :action => "create" }, { :path => "photos", :method => :post })
 </ruby>
-You can also use the RESTful helpers to test recognition of a RESTful route:
+You can also use the resourceful helpers to test recognition of a RESTful route:
 <ruby>
 assert_recognizes new_photo_url, { :path => "photos", :method => :post }
@@ -899,6 +786,8 @@ h3. Changelog
 "Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/3
+* April 10, 2010: Updated guide to remove outdated and superfluous information, and to provide information about new features, by "Yehuda Katz":http://www.yehudakatz.com
+* April 2, 2010: Updated guide to match new Routing DSL in Rails 3, by "Rizwan Reza":http://www.rizwanreza.com/
 * Febuary 1, 2010: Modifies the routing documentation to match new routing DSL in Rails 3, by Prem Sichanugrist
 * October 4, 2008: Added additional detail on specifying verbs for resource member/collection routes, by "Mike Gunderloy":credits.html#mgunderloy
 * September 23, 2008: Added section on namespaced controllers and routing, by "Mike Gunderloy":credits.html#mgunderloy