vendor/rails/railties/doc/guides/html/routing_outside_in.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
   3 <head>
   4         <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   5         <title>Rails Routing from the Outside In</title>
   6         <!--[if lt IE 8]>
   7         <script src="http://ie7-js.googlecode.com/svn/version/2.0(beta3)/IE8.js" type="text/javascript"></script>
   8         <![endif]-->
   9         <link href="stylesheets/base.css" media="screen" rel="Stylesheet" type="text/css" />
  10         <link href="stylesheets/forms.css" media="screen" rel="Stylesheet" type="text/css" />
  11         <link href="stylesheets/more.css" media="screen" rel="Stylesheet" type="text/css" />
  12         <style type="text/css">
  13                 div#container {
  14         max-width: 900px;
  15         padding-bottom: 3em;
  16 }
  17
  18 div#content {
  19         margin-left: 200px;
  20 }
  21
  22 div#container.notoc {
  23         max-width: 600px;
  24 }
  25
  26 .notoc div#content {
  27         margin-left: 0;
  28 }
  29
  30 pre {
  31         line-height: 1.4em;
  32 }
  33
  34 #content p tt {
  35         background: #eeeeee;
  36         border: solid 1px #cccccc;
  37         padding: 3px;
  38 }
  39
  40 dt {
  41         font-weight: bold;
  42 }
  43
  44 #content dt tt {
  45         font-size: 10pt;
  46 }
  47
  48 dd {
  49         margin-left: 3em;
  50 }
  51
  52 #content dt tt, #content pre tt {
  53         background: none;
  54         padding: 0;
  55         border: 0;
  56 }
  57
  58 #content .olist ol {
  59         margin-left: 2em;
  60 }
  61
  62 #header {
  63         position: relative;
  64         max-width: 840px;
  65         margin-left: auto;
  66         margin-right: auto;
  67 }
  68
  69 #header.notoc {
  70         max-width: 580px;
  71 }
  72
  73 #logo {
  74         position: absolute;
  75         left: 10px;
  76         top: 10px;
  77         width: 110px;
  78         height: 140px;
  79 }
  80
  81 div#header h1#site_title {
  82         background: url('images/ruby_on_rails_by_mike_rundle2.gif') top left no-repeat;
  83         position: absolute;
  84         width: 392px;
  85         height: 55px;
  86         left: 145px;
  87         top: 20px;
  88         margin: 0;
  89         padding: 0;
  90 }
  91
  92 #site_title span {
  93         display: none;
  94 }
  95
  96 #site_title_tagline {
  97         display: none;
  98 }
  99
 100 ul#navMain {
 101         position: absolute;
 102         margin: 0;
 103         padding: 0;
 104         top: 97px;
 105         left: 145px;
 106 }
 107
 108 .left-floaty, .right-floaty {
 109         padding: 15px;
 110 }
 111
 112 .admonitionblock,
 113 .tableblock {
 114         margin-left: 1em;
 115         margin-right: 1em;
 116         margin-top: 0.25em;
 117         margin-bottom: 1em;
 118 }
 119
 120 .admonitionblock .icon {
 121         padding-right: 8px;
 122 }
 123
 124 .admonitionblock .content {
 125         border: solid 1px #ffda78;
 126         background: #fffebd;
 127         padding: 10px;
 128         padding-top: 8px;
 129         padding-bottom: 8px;
 130 }
 131
 132 .admonitionblock .title {
 133         font-size: 140%;
 134         margin-bottom: 0.5em;
 135 }
 136
 137 .tableblock table {
 138         border: solid 1px #aaaaff;
 139         background: #f0f0ff;
 140 }
 141
 142 .tableblock th {
 143         background: #e0e0e0;
 144 }
 145
 146 .tableblock th,
 147 .tableblock td {
 148         padding: 3px;
 149         padding-left: 5px;
 150         padding-right: 5px;
 151 }
 152
 153 .sidebarblock {
 154         margin-top: 0.25em;
 155         margin: 1em;
 156         border: solid 1px #ccccbb;
 157         padding: 8px;
 158         background: #ffffe0;
 159 }
 160
 161 .sidebarblock .sidebar-title {
 162         font-size: 140%;
 163         font-weight: 600;
 164         margin-bottom: 0.3em;
 165 }
 166
 167 .sidebarblock .sidebar-content > .para:last-child > p {
 168         margin-bottom: 0;
 169 }
 170
 171 .sidebarblock .sidebar-title a {
 172         text-decoration: none;
 173 }
 174
 175 .sidebarblock .sidebar-title a:hover {
 176         text-decoration: underline;
 177 }
 178
 179         </style>
 180 </head>
 181 <body>
 182         <div id="header" >
 183                 <div id="logo">
 184                         <a href="index.html" title="Ruby on Rails"><img src="images/rails_logo_remix.gif" alt="Rails" height="140" width="110" /></a>
 185                 </div>
 186
 187                 <h1 id="site_title"><span>Ruby on Rails</span></h1>
 188                 <h2 id="site_title_tagline">Sustainable productivity for web-application development</h2>
 189
 190                 <ul id="navMain">
 191                         <li class="first-child"><a href="http://www.rubyonrails.org/" title="Ruby on Rails" class="ruby_on_rails">Ruby on Rails</a></li>
 192                         <li><a class="manuals" href="index.html" title="Manuals Index">Guides Index</a></li>
 193                 </ul>
 194         </div>
 195
 196         <div id="container">
 197
 198                 <div id="sidebar">
 199                         <h2>Chapters</h2>
 200                         <ol>
 201                                         <li>
 202                                         <a href="#_the_dual_purpose_of_routing">The Dual Purpose of Routing</a>
 203                                                 <ul>
 204
 205                                                         <li><a href="#_connecting_urls_to_code">Connecting URLs to Code</a></li>
 206
 207                                                         <li><a href="#_generating_urls_from_code">Generating URLs from Code</a></li>
 208
 209                                                 </ul>
 210                                         </li>
 211                                         <li>
 212                                         <a href="#_quick_tour_of_routes_rb">Quick Tour of Routes.rb</a>
 213                                                 <ul>
 214
 215                                                         <li><a href="#_processing_the_file">Processing the File</a></li>
 216
 217                                                         <li><a href="#_restful_routes">RESTful Routes</a></li>
 218
 219                                                         <li><a href="#_named_routes">Named Routes</a></li>
 220
 221                                                         <li><a href="#_nested_routes">Nested Routes</a></li>
 222
 223                                                         <li><a href="#_regular_routes">Regular Routes</a></li>
 224
 225                                                         <li><a href="#_default_routes">Default Routes</a></li>
 226
 227                                                 </ul>
 228                                         </li>
 229                                         <li>
 230                                         <a href="#_restful_routing_the_rails_default">RESTful Routing: the Rails Default</a>
 231                                                 <ul>
 232
 233                                                         <li><a href="#_what_is_rest">What is REST?</a></li>
 234
 235                                                         <li><a href="#_crud_verbs_and_actions">CRUD, Verbs, and Actions</a></li>
 236
 237                                                         <li><a href="#_urls_and_paths">URLs and Paths</a></li>
 238
 239                                                         <li><a href="#_defining_multiple_resources_at_the_same_time">Defining Multiple Resources at the Same Time</a></li>
 240
 241                                                         <li><a href="#_singular_resources">Singular Resources</a></li>
 242
 243                                                         <li><a href="#_customizing_resources">Customizing Resources</a></li>
 244
 245                                                         <li><a href="#_controller_namespaces_and_routing">Controller Namespaces and Routing</a></li>
 246
 247                                                         <li><a href="#_nested_resources">Nested Resources</a></li>
 248
 249                                                         <li><a href="#_route_generation_from_arrays">Route Generation from Arrays</a></li>
 250
 251                                                         <li><a href="#_namespaced_resources">Namespaced Resources</a></li>
 252
 253                                                         <li><a href="#_adding_more_restful_actions">Adding More RESTful Actions</a></li>
 254
 255                                                 </ul>
 256                                         </li>
 257                                         <li>
 258                                         <a href="#_regular_routes_2">Regular Routes</a>
 259                                                 <ul>
 260
 261                                                         <li><a href="#_bound_parameters">Bound Parameters</a></li>
 262
 263                                                         <li><a href="#_wildcard_components">Wildcard Components</a></li>
 264
 265                                                         <li><a href="#_static_text">Static Text</a></li>
 266
 267                                                         <li><a href="#_querystring_parameters">Querystring Parameters</a></li>
 268
 269                                                         <li><a href="#_defining_defaults">Defining Defaults</a></li>
 270
 271                                                         <li><a href="#_named_routes_2">Named Routes</a></li>
 272
 273                                                         <li><a href="#_route_requirements">Route Requirements</a></li>
 274
 275                                                         <li><a href="#_route_conditions">Route Conditions</a></li>
 276
 277                                                         <li><a href="#_route_globbing">Route Globbing</a></li>
 278
 279                                                         <li><a href="#_route_options">Route Options</a></li>
 280
 281                                                 </ul>
 282                                         </li>
 283                                         <li>
 284                                         <a href="#_formats_and_respond_to">Formats and respond_to</a>
 285                                                 <ul>
 286
 287                                                         <li><a href="#_specifying_the_format_with_an_http_header">Specifying the Format with an HTTP Header</a></li>
 288
 289                                                         <li><a href="#_recognized_mime_types">Recognized MIME types</a></li>
 290
 291                                                 </ul>
 292                                         </li>
 293                                         <li>
 294                                         <a href="#_the_default_routes">The Default Routes</a>
 295                                         </li>
 296                                         <li>
 297                                         <a href="#_the_empty_route">The Empty Route</a>
 298                                                 <ul>
 299
 300                                                         <li><a href="#_using_map_root">Using map.root</a></li>
 301
 302                                                         <li><a href="#_connecting_the_empty_string">Connecting the Empty String</a></li>
 303
 304                                                 </ul>
 305                                         </li>
 306                                         <li>
 307                                         <a href="#_inspecting_and_testing_routes">Inspecting and Testing Routes</a>
 308                                                 <ul>
 309
 310                                                         <li><a href="#_seeing_existing_routes_with_rake">Seeing Existing Routes with rake</a></li>
 311
 312                                                         <li><a href="#_testing_routes">Testing Routes</a></li>
 313
 314                                                 </ul>
 315                                         </li>
 316                                         <li>
 317                                         <a href="#_changelog">Changelog</a>
 318                                         </li>
 319                         </ol>
 320                 </div>
 321
 322                 <div id="content">
 323                                 <h1>Rails Routing from the Outside In</h1>
 324                         <div id="preamble">
 325 <div class="sectionbody">
 326 <div class="para"><p>This guide covers the user-facing features of Rails routing. By referring to this guide, you will be able to:</p></div>
 327 <div class="ilist"><ul>
 328 <li>
 329 <p>
 330 Understand the purpose of routing
 331 </p>
 332 </li>
 333 <li>
 334 <p>
 335 Decipher the code in <tt>routes.rb</tt>
 336 </p>
 337 </li>
 338 <li>
 339 <p>
 340 Construct your own routes, using either the classic hash style or the now-preferred RESTful style
 341 </p>
 342 </li>
 343 <li>
 344 <p>
 345 Identify how a route will map to a controller and action
 346 </p>
 347 </li>
 348 </ul></div>
 349 </div>
 350 </div>
 351 <h2 id="_the_dual_purpose_of_routing">1. The Dual Purpose of Routing</h2>
 352 <div class="sectionbody">
 353 <div class="para"><p>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.</p></div>
 354 <h3 id="_connecting_urls_to_code">1.1. Connecting URLs to Code</h3>
 355 <div class="para"><p>When your Rails application receives an incoming HTTP request, say</p></div>
 356 <div class="listingblock">
 357 <div class="content">
 358 <pre><tt>GET /patients/17</tt></pre>
 359 </div></div>
 360 <div class="para"><p>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 <tt>show</tt> action within the <tt>patients</tt> controller, displaying the details of the patient whose ID is 17.</p></div>
 361 <h3 id="_generating_urls_from_code">1.2. Generating URLs from Code</h3>
 362 <div class="para"><p>Routing also works in reverse. If your application contains this code:</p></div>
 363 <div class="listingblock">
 364 <div class="content"><!-- Generator: GNU source-highlight 2.9
 365 by Lorenzo Bettini
 366 http://www.lorenzobettini.it
 367 http://www.gnu.org/software/src-highlite -->
 368 <pre><tt><span style="color: #009900">@patient</span> <span style="color: #990000">=</span> Patient<span style="color: #990000">.</span>find<span style="color: #990000">(</span><span style="color: #993399">17</span><span style="color: #990000">)</span>
 369 <span style="color: #FF0000">&lt;%= link_to "Patient Record", patient_path(@patient) %&gt;</span>
 370 </tt></pre></div></div>
 371 <div class="para"><p>Then the routing engine is the piece that translates that to a link to a URL such as <tt>http://example.com/patients/17</tt>. 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.</p></div>
 372 <div class="admonitionblock">
 373 <table><tr>
 374 <td class="icon">
 375 <img src="./images/icons/note.png" alt="Note" />
 376 </td>
 377 <td class="content">Patient needs to be declared as a resource for this style of translation via a named route to be available.</td>
 378 </tr></table>
 379 </div>
 380 </div>
 381 <h2 id="_quick_tour_of_routes_rb">2. Quick Tour of Routes.rb</h2>
 382 <div class="sectionbody">
 383 <div class="para"><p>There are two components to routing in Rails: the routing engine itself, which is supplied as part of Rails, and the file <tt>config/routes.rb</tt>, which contains the actual routes that will be used by your application. Learning exactly what you can put in <tt>routes.rb</tt> is the main topic of this guide, but before we dig in let's get a quick overview.</p></div>
 384 <h3 id="_processing_the_file">2.1. Processing the File</h3>
 385 <div class="para"><p>In format, <tt>routes.rb</tt> is nothing more than one big block sent to <tt>ActionController::Routing::Routes.draw</tt>. 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:</p></div>
 386 <div class="ilist"><ul>
 387 <li>
 388 <p>
 389 RESTful Routes
 390 </p>
 391 </li>
 392 <li>
 393 <p>
 394 Named Routes
 395 </p>
 396 </li>
 397 <li>
 398 <p>
 399 Nested Routes
 400 </p>
 401 </li>
 402 <li>
 403 <p>
 404 Regular Routes
 405 </p>
 406 </li>
 407 <li>
 408 <p>
 409 Default Routes
 410 </p>
 411 </li>
 412 </ul></div>
 413 <div class="para"><p>Each of these types of route is covered in more detail later in this guide.</p></div>
 414 <div class="para"><p>The <tt>routes.rb</tt> file is processed from top to bottom when a request comes in. The request will be dispatched to the first matching route. If there is no matching route, then Rails returns HTTP status 404 to the caller.</p></div>
 415 <h3 id="_restful_routes">2.2. RESTful Routes</h3>
 416 <div class="para"><p>RESTful routes take advantage of the built-in REST orientation of Rails to wrap up a lot of routing information in a single declaration. A RESTful route looks like this:</p></div>
 417 <div class="listingblock">
 418 <div class="content"><!-- Generator: GNU source-highlight 2.9
 419 by Lorenzo Bettini
 420 http://www.lorenzobettini.it
 421 http://www.gnu.org/software/src-highlite -->
 422 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>books
 423 </tt></pre></div></div>
 424 <h3 id="_named_routes">2.3. Named Routes</h3>
 425 <div class="para"><p>Named routes give you very readable links in your code, as well as handling incoming requests. Here's a typical named route:</p></div>
 426 <div class="listingblock">
 427 <div class="content"><!-- Generator: GNU source-highlight 2.9
 428 by Lorenzo Bettini
 429 http://www.lorenzobettini.it
 430 http://www.gnu.org/software/src-highlite -->
 431 <pre><tt>map<span style="color: #990000">.</span>login <span style="color: #FF0000">'/login'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'sessions'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'new'</span>
 432 </tt></pre></div></div>
 433 <h3 id="_nested_routes">2.4. Nested Routes</h3>
 434 <div class="para"><p>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:</p></div>
 435 <div class="listingblock">
 436 <div class="content"><!-- Generator: GNU source-highlight 2.9
 437 by Lorenzo Bettini
 438 http://www.lorenzobettini.it
 439 http://www.gnu.org/software/src-highlite -->
 440 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>assemblies <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>assemblies<span style="color: #990000">|</span>
 441   assemblies<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>parts
 442 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
 443 </tt></pre></div></div>
 444 <h3 id="_regular_routes">2.5. Regular Routes</h3>
 445 <div class="para"><p>In many applications, you'll also see non-RESTful routing, which explicitly connects the parts of a URL to a particular action. For example,</p></div>
 446 <div class="listingblock">
 447 <div class="content"><!-- Generator: GNU source-highlight 2.9
 448 by Lorenzo Bettini
 449 http://www.lorenzobettini.it
 450 http://www.gnu.org/software/src-highlite -->
 451 <pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">'parts/:number'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'inventory'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'show'</span>
 452 </tt></pre></div></div>
 453 <h3 id="_default_routes">2.6. Default Routes</h3>
 454 <div class="para"><p>The default routes are a safety net that catch otherwise-unrouted requests. Many Rails applications will contain this pair of default routes:</p></div>
 455 <div class="listingblock">
 456 <div class="content"><!-- Generator: GNU source-highlight 2.9
 457 by Lorenzo Bettini
 458 http://www.lorenzobettini.it
 459 http://www.gnu.org/software/src-highlite -->
 460 <pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':controller/:action/:id'</span>
 461 map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':controller/:action/:id.:format'</span>
 462 </tt></pre></div></div>
 463 <div class="para"><p>These default routes are automatically generated when you create a new Rails application. If you're using RESTful routing for everything in your application, you will probably want to remove them. But be sure you're not using the default routes before you remove them!</p></div>
 464 </div>
 465 <h2 id="_restful_routing_the_rails_default">3. RESTful Routing: the Rails Default</h2>
 466 <div class="sectionbody">
 467 <div class="para"><p>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.</p></div>
 468 <h3 id="_what_is_rest">3.1. What is REST?</h3>
 469 <div class="para"><p>The foundation of RESTful routing is generally considered to be Roy Fielding's doctoral thesis, <a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">Architectural Styles and the Design of Network-based Software Architectures</a>. 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:</p></div>
 470 <div class="ilist"><ul>
 471 <li>
 472 <p>
 473 Using resource identifiers (which, for the purposes of discussion, you can think of as URLs) to represent resources
 474 </p>
 475 </li>
 476 <li>
 477 <p>
 478 Transferring representations of the state of that resource between system components.
 479 </p>
 480 </li>
 481 </ul></div>
 482 <div class="para"><p>For example, to a Rails application a request such as this:</p></div>
 483 <div class="para"><p><tt>DELETE /photos/17</tt></p></div>
 484 <div class="para"><p>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.</p></div>
 485 <h3 id="_crud_verbs_and_actions">3.2. CRUD, Verbs, and Actions</h3>
 486 <div class="para"><p>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</p></div>
 487 <div class="listingblock">
 488 <div class="content"><!-- Generator: GNU source-highlight 2.9
 489 by Lorenzo Bettini
 490 http://www.lorenzobettini.it
 491 http://www.gnu.org/software/src-highlite -->
 492 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos
 493 </tt></pre></div></div>
 494 <div class="para"><p>creates seven different routes in your application:</p></div>
 495 <div class="tableblock">
 496 <table rules="all"
 497 frame="hsides"
 498 cellspacing="0" cellpadding="4">
 499 <col width="125" />
 500 <col width="182" />
 501 <col width="137" />
 502 <col width="102" />
 503 <col width="502" />
 504 <thead>
 505   <tr>
 506     <th align="left">
 507     HTTP verb
 508     </th>
 509     <th align="left">
 510     URL
 511     </th>
 512     <th align="left">
 513     controller
 514     </th>
 515     <th align="left">
 516     action
 517     </th>
 518     <th align="left">
 519     used for
 520     </th>
 521   </tr>
 522 </thead>
 523 <tbody valign="top">
 524   <tr>
 525     <td align="left">
 526     GET
 527     </td>
 528     <td align="left">
 529     /photos
 530     </td>
 531     <td align="left">
 532     Photos
 533     </td>
 534     <td align="left">
 535     index
 536     </td>
 537     <td align="left">
 538     display a list of all photos
 539     </td>
 540   </tr>
 541   <tr>
 542     <td align="left">
 543     GET
 544     </td>
 545     <td align="left">
 546     /photos/new
 547     </td>
 548     <td align="left">
 549     Photos
 550     </td>
 551     <td align="left">
 552     new
 553     </td>
 554     <td align="left">
 555     return an HTML form for creating a new photo
 556     </td>
 557   </tr>
 558   <tr>
 559     <td align="left">
 560     POST
 561     </td>
 562     <td align="left">
 563     /photos
 564     </td>
 565     <td align="left">
 566     Photos
 567     </td>
 568     <td align="left">
 569     create
 570     </td>
 571     <td align="left">
 572     create a new photo
 573     </td>
 574   </tr>
 575   <tr>
 576     <td align="left">
 577     GET
 578     </td>
 579     <td align="left">
 580     /photos/1
 581     </td>
 582     <td align="left">
 583     Photos
 584     </td>
 585     <td align="left">
 586     show
 587     </td>
 588     <td align="left">
 589     display a specific photo
 590     </td>
 591   </tr>
 592   <tr>
 593     <td align="left">
 594     GET
 595     </td>
 596     <td align="left">
 597     /photos/1/edit
 598     </td>
 599     <td align="left">
 600     Photos
 601     </td>
 602     <td align="left">
 603     edit
 604     </td>
 605     <td align="left">
 606     return an HTML form for editing a photo
 607     </td>
 608   </tr>
 609   <tr>
 610     <td align="left">
 611     PUT
 612     </td>
 613     <td align="left">
 614     /photos/1
 615     </td>
 616     <td align="left">
 617     Photos
 618     </td>
 619     <td align="left">
 620     update
 621     </td>
 622     <td align="left">
 623     update a specific photo
 624     </td>
 625   </tr>
 626   <tr>
 627     <td align="left">
 628     DELETE
 629     </td>
 630     <td align="left">
 631     /photos/1
 632     </td>
 633     <td align="left">
 634     Photos
 635     </td>
 636     <td align="left">
 637     destroy
 638     </td>
 639     <td align="left">
 640     delete a specific photo
 641     </td>
 642   </tr>
 643 </tbody>
 644 </table>
 645 </div>
 646 <div class="para"><p>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 <tt>params[:id]</tt>.</p></div>
 647 <div class="admonitionblock">
 648 <table><tr>
 649 <td class="icon">
 650 <img src="./images/icons/tip.png" alt="Tip" />
 651 </td>
 652 <td class="content">If you consistently use RESTful routes in your application, you should disable the default routes in <tt>routes.rb</tt> so that Rails will enforce the mapping between HTTP verbs and routes.</td>
 653 </tr></table>
 654 </div>
 655 <h3 id="_urls_and_paths">3.3. URLs and Paths</h3>
 656 <div class="para"><p>Creating a RESTful route will also make available a pile of helpers within your application:</p></div>
 657 <div class="ilist"><ul>
 658 <li>
 659 <p>
 660 <tt>photos_url</tt> and <tt>photos_path</tt> map to the path for the index and create actions
 661 </p>
 662 </li>
 663 <li>
 664 <p>
 665 <tt>new_photo_url</tt> and <tt>new_photo_path</tt> map to the path for the new action
 666 </p>
 667 </li>
 668 <li>
 669 <p>
 670 <tt>edit_photo_url</tt> and <tt>edit_photo_path</tt> map to the path for the edit action
 671 </p>
 672 </li>
 673 <li>
 674 <p>
 675 <tt>photo_url</tt> and <tt>photo_path</tt> map to the path for the show, update, and destroy actions
 676 </p>
 677 </li>
 678 </ul></div>
 679 <div class="admonitionblock">
 680 <table><tr>
 681 <td class="icon">
 682 <img src="./images/icons/note.png" alt="Note" />
 683 </td>
 684 <td class="content">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.</td>
 685 </tr></table>
 686 </div>
 687 <div class="para"><p>In each case, the <tt>_url</tt> helper generates a string containing the entire URL that the application will understand, while the <tt>_path</tt> helper generates a string containing the relative path from the root of the application. For example:</p></div>
 688 <div class="listingblock">
 689 <div class="content"><!-- Generator: GNU source-highlight 2.9
 690 by Lorenzo Bettini
 691 http://www.lorenzobettini.it
 692 http://www.gnu.org/software/src-highlite -->
 693 <pre><tt>photos_url  <span style="font-style: italic"><span style="color: #9A1900"># =&gt; "http://www.example.com/photos"</span></span>
 694 photos_path <span style="font-style: italic"><span style="color: #9A1900"># =&gt; "/photos"</span></span>
 695 </tt></pre></div></div>
 696 <h3 id="_defining_multiple_resources_at_the_same_time">3.4. Defining Multiple Resources at the Same Time</h3>
 697 <div class="para"><p>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 <tt>map.resources</tt>:</p></div>
 698 <div class="listingblock">
 699 <div class="content"><!-- Generator: GNU source-highlight 2.9
 700 by Lorenzo Bettini
 701 http://www.lorenzobettini.it
 702 http://www.gnu.org/software/src-highlite -->
 703 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>books<span style="color: #990000">,</span> <span style="color: #990000">:</span>videos
 704 </tt></pre></div></div>
 705 <div class="para"><p>This has exactly the same effect as</p></div>
 706 <div class="listingblock">
 707 <div class="content"><!-- Generator: GNU source-highlight 2.9
 708 by Lorenzo Bettini
 709 http://www.lorenzobettini.it
 710 http://www.gnu.org/software/src-highlite -->
 711 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos
 712 map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>books
 713 map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>videos
 714 </tt></pre></div></div>
 715 <h3 id="_singular_resources">3.5. Singular Resources</h3>
 716 <div class="para"><p>You can also apply RESTful routing to singleton resources within your application. In this case, you use <tt>map.resource</tt> instead of <tt>map.resources</tt> and the route generation is slightly different. For example, a routing entry of</p></div>
 717 <div class="listingblock">
 718 <div class="content"><!-- Generator: GNU source-highlight 2.9
 719 by Lorenzo Bettini
 720 http://www.lorenzobettini.it
 721 http://www.gnu.org/software/src-highlite -->
 722 <pre><tt>map<span style="color: #990000">.</span>resource <span style="color: #990000">:</span>geocoder
 723 </tt></pre></div></div>
 724 <div class="para"><p>creates six different routes in your application:</p></div>
 725 <div class="tableblock">
 726 <table rules="all"
 727 frame="hsides"
 728 cellspacing="0" cellpadding="4">
 729 <col width="125" />
 730 <col width="182" />
 731 <col width="137" />
 732 <col width="102" />
 733 <col width="502" />
 734 <thead>
 735   <tr>
 736     <th align="left">
 737     HTTP verb
 738     </th>
 739     <th align="left">
 740     URL
 741     </th>
 742     <th align="left">
 743     controller
 744     </th>
 745     <th align="left">
 746     action
 747     </th>
 748     <th align="left">
 749     used for
 750     </th>
 751   </tr>
 752 </thead>
 753 <tbody valign="top">
 754   <tr>
 755     <td align="left">
 756     GET
 757     </td>
 758     <td align="left">
 759     /geocoder/new
 760     </td>
 761     <td align="left">
 762     Geocoders
 763     </td>
 764     <td align="left">
 765     new
 766     </td>
 767     <td align="left">
 768     return an HTML form for creating the new geocoder
 769     </td>
 770   </tr>
 771   <tr>
 772     <td align="left">
 773     POST
 774     </td>
 775     <td align="left">
 776     /geocoder
 777     </td>
 778     <td align="left">
 779     Geocoders
 780     </td>
 781     <td align="left">
 782     create
 783     </td>
 784     <td align="left">
 785     create the new geocoder
 786     </td>
 787   </tr>
 788   <tr>
 789     <td align="left">
 790     GET
 791     </td>
 792     <td align="left">
 793     /geocoder
 794     </td>
 795     <td align="left">
 796     Geocoders
 797     </td>
 798     <td align="left">
 799     show
 800     </td>
 801     <td align="left">
 802     display the one and only geocoder resource
 803     </td>
 804   </tr>
 805   <tr>
 806     <td align="left">
 807     GET
 808     </td>
 809     <td align="left">
 810     /geocoder/edit
 811     </td>
 812     <td align="left">
 813     Geocoders
 814     </td>
 815     <td align="left">
 816     edit
 817     </td>
 818     <td align="left">
 819     return an HTML form for editing the geocoder
 820     </td>
 821   </tr>
 822   <tr>
 823     <td align="left">
 824     PUT
 825     </td>
 826     <td align="left">
 827     /geocoder
 828     </td>
 829     <td align="left">
 830     Geocoders
 831     </td>
 832     <td align="left">
 833     update
 834     </td>
 835     <td align="left">
 836     update the one and only geocoder resource
 837     </td>
 838   </tr>
 839   <tr>
 840     <td align="left">
 841     DELETE
 842     </td>
 843     <td align="left">
 844     /geocoder
 845     </td>
 846     <td align="left">
 847     Geocoders
 848     </td>
 849     <td align="left">
 850     destroy
 851     </td>
 852     <td align="left">
 853     delete the geocoder resource
 854     </td>
 855   </tr>
 856 </tbody>
 857 </table>
 858 </div>
 859 <div class="admonitionblock">
 860 <table><tr>
 861 <td class="icon">
 862 <img src="./images/icons/note.png" alt="Note" />
 863 </td>
 864 <td class="content">Even though the name of the resource is singular in <tt>routes.rb</tt>, the matching controller is still plural.</td>
 865 </tr></table>
 866 </div>
 867 <div class="para"><p>A singular RESTful route generates an abbreviated set of helpers:</p></div>
 868 <div class="ilist"><ul>
 869 <li>
 870 <p>
 871 <tt>new_geocoder_url</tt> and <tt>new_geocoder_path</tt> map to the path for the new action
 872 </p>
 873 </li>
 874 <li>
 875 <p>
 876 <tt>edit_geocoder_url</tt> and <tt>edit_geocoder_path</tt> map to the path for the edit action
 877 </p>
 878 </li>
 879 <li>
 880 <p>
 881 <tt>geocoder_url</tt> and <tt>geocoder_path</tt> map to the path for the create, show, update, and destroy actions
 882 </p>
 883 </li>
 884 </ul></div>
 885 <h3 id="_customizing_resources">3.6. Customizing Resources</h3>
 886 <div class="para"><p>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:</p></div>
 887 <div class="ilist"><ul>
 888 <li>
 889 <p>
 890 <tt>:controller</tt>
 891 </p>
 892 </li>
 893 <li>
 894 <p>
 895 <tt>:singular</tt>
 896 </p>
 897 </li>
 898 <li>
 899 <p>
 900 <tt>:requirements</tt>
 901 </p>
 902 </li>
 903 <li>
 904 <p>
 905 <tt>:conditions</tt>
 906 </p>
 907 </li>
 908 <li>
 909 <p>
 910 <tt>:as</tt>
 911 </p>
 912 </li>
 913 <li>
 914 <p>
 915 <tt>:path_names</tt>
 916 </p>
 917 </li>
 918 <li>
 919 <p>
 920 <tt>:path_prefix</tt>
 921 </p>
 922 </li>
 923 <li>
 924 <p>
 925 <tt>:name_prefix</tt>
 926 </p>
 927 </li>
 928 <li>
 929 <p>
 930 <tt>:only</tt>
 931 </p>
 932 </li>
 933 <li>
 934 <p>
 935 <tt>:except</tt>
 936 </p>
 937 </li>
 938 </ul></div>
 939 <div class="para"><p>You can also add additional routes via the <tt>:member</tt> and <tt>:collection</tt> options, which are discussed later in this guide.</p></div>
 940 <h4 id="_using_controller">3.6.1. Using :controller</h4>
 941 <div class="para"><p>The <tt>:controller</tt> option lets you use a controller name that is different from the public-facing resource name. For example, this routing entry:</p></div>
 942 <div class="listingblock">
 943 <div class="content"><!-- Generator: GNU source-highlight 2.9
 944 by Lorenzo Bettini
 945 http://www.lorenzobettini.it
 946 http://www.gnu.org/software/src-highlite -->
 947 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"images"</span>
 948 </tt></pre></div></div>
 949 <div class="para"><p>will recognize incoming URLs containing <tt>photo</tt> but route the requests to the Images controller:</p></div>
 950 <div class="tableblock">
 951 <table rules="all"
 952 frame="hsides"
 953 cellspacing="0" cellpadding="4">
 954 <col width="125" />
 955 <col width="182" />
 956 <col width="137" />
 957 <col width="102" />
 958 <col width="502" />
 959 <thead>
 960   <tr>
 961     <th align="left">
 962     HTTP verb
 963     </th>
 964     <th align="left">
 965     URL
 966     </th>
 967     <th align="left">
 968     controller
 969     </th>
 970     <th align="left">
 971     action
 972     </th>
 973     <th align="left">
 974     used for
 975     </th>
 976   </tr>
 977 </thead>
 978 <tbody valign="top">
 979   <tr>
 980     <td align="left">
 981     GET
 982     </td>
 983     <td align="left">
 984     /photos
 985     </td>
 986     <td align="left">
 987     Images
 988     </td>
 989     <td align="left">
 990     index
 991     </td>
 992     <td align="left">
 993     display a list of all images
 994     </td>
 995   </tr>
 996   <tr>
 997     <td align="left">
 998     GET
 999     </td>
1000     <td align="left">
1001     /photos/new
1002     </td>
1003     <td align="left">
1004     Images
1005     </td>
1006     <td align="left">
1007     new
1008     </td>
1009     <td align="left">
1010     return an HTML form for creating a new image
1011     </td>
1012   </tr>
1013   <tr>
1014     <td align="left">
1015     POST
1016     </td>
1017     <td align="left">
1018     /photos
1019     </td>
1020     <td align="left">
1021     Images
1022     </td>
1023     <td align="left">
1024     create
1025     </td>
1026     <td align="left">
1027     create a new image
1028     </td>
1029   </tr>
1030   <tr>
1031     <td align="left">
1032     GET
1033     </td>
1034     <td align="left">
1035     /photos/1
1036     </td>
1037     <td align="left">
1038     Images
1039     </td>
1040     <td align="left">
1041     show
1042     </td>
1043     <td align="left">
1044     display a specific image
1045     </td>
1046   </tr>
1047   <tr>
1048     <td align="left">
1049     GET
1050     </td>
1051     <td align="left">
1052     /photos/1/edit
1053     </td>
1054     <td align="left">
1055     Images
1056     </td>
1057     <td align="left">
1058     edit
1059     </td>
1060     <td align="left">
1061     return an HTML form for editing a image
1062     </td>
1063   </tr>
1064   <tr>
1065     <td align="left">
1066     PUT
1067     </td>
1068     <td align="left">
1069     /photos/1
1070     </td>
1071     <td align="left">
1072     Images
1073     </td>
1074     <td align="left">
1075     update
1076     </td>
1077     <td align="left">
1078     update a specific image
1079     </td>
1080   </tr>
1081   <tr>
1082     <td align="left">
1083     DELETE
1084     </td>
1085     <td align="left">
1086     /photos/1
1087     </td>
1088     <td align="left">
1089     Images
1090     </td>
1091     <td align="left">
1092     destroy
1093     </td>
1094     <td align="left">
1095     delete a specific image
1096     </td>
1097   </tr>
1098 </tbody>
1099 </table>
1100 </div>
1101 <div class="admonitionblock">
1102 <table><tr>
1103 <td class="icon">
1104 <img src="./images/icons/note.png" alt="Note" />
1105 </td>
1106 <td class="content">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 <tt>photos_path</tt>, <tt>new_photo_path</tt>, and so on.</td>
1107 </tr></table>
1108 </div>
1109 <h3 id="_controller_namespaces_and_routing">3.7. Controller Namespaces and Routing</h3>
1110 <div class="para"><p>Rails allows you to group your controllers into namespaces by saving them in folders underneath <tt>app/controllers</tt>. The <tt>:controller</tt> 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 <tt>admin</tt> folder:</p></div>
1111 <div class="listingblock">
1112 <div class="content"><!-- Generator: GNU source-highlight 2.9
1113 by Lorenzo Bettini
1114 http://www.lorenzobettini.it
1115 http://www.gnu.org/software/src-highlite -->
1116 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>adminphotos<span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"admin/photos"</span>
1117 </tt></pre></div></div>
1118 <div class="para"><p>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 <tt>adminphoto_path</tt> helper, and you follow a link generated with <tt>&lt;%= link_to "show", adminphoto(1) %&gt;</tt> you will end up on the view generated by <tt>admin/photos/show</tt> but you will also end up in the same place if you have <tt>&lt;%= link_to "show", {:controller &#8658; "photos", :action &#8658; "show"} %&gt;</tt> because Rails will generate the show URL relative to the current URL.</p></div>
1119 <div class="admonitionblock">
1120 <table><tr>
1121 <td class="icon">
1122 <img src="./images/icons/tip.png" alt="Tip" />
1123 </td>
1124 <td class="content">If you want to guarantee that a link goes to a top-level controller, use a preceding slash to anchor the controller name: <tt>&lt;%= link_to "show", {:controller &#8658; "/photos", :action &#8658; "show"} %&gt;</tt></td>
1125 </tr></table>
1126 </div>
1127 <div class="para"><p>You can also specify a controller namespace with the <tt>:namespace</tt> option instead of a path:</p></div>
1128 <div class="listingblock">
1129 <div class="content"><!-- Generator: GNU source-highlight 2.9
1130 by Lorenzo Bettini
1131 http://www.lorenzobettini.it
1132 http://www.gnu.org/software/src-highlite -->
1133 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>adminphotos<span style="color: #990000">,</span> <span style="color: #990000">:</span>namespace <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"admin"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"photos"</span>
1134 </tt></pre></div></div>
1135 <div class="para"><p>This can be especially useful when combined with <tt>with_options</tt> to map multiple namespaced routes together:</p></div>
1136 <div class="listingblock">
1137 <div class="content"><!-- Generator: GNU source-highlight 2.9
1138 by Lorenzo Bettini
1139 http://www.lorenzobettini.it
1140 http://www.gnu.org/software/src-highlite -->
1141 <pre><tt>map<span style="color: #990000">.</span>with_options<span style="color: #990000">(:</span>namespace <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"admin"</span><span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>admin<span style="color: #990000">|</span>
1142   admin<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>videos
1143 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1144 </tt></pre></div></div>
1145 <div class="para"><p>That would give you routing for <tt>admin/photos</tt> and <tt>admin/videos</tt> controllers.</p></div>
1146 <h4 id="_using_singular">3.7.1. Using :singular</h4>
1147 <div class="para"><p>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 <tt>:singular</tt> option:</p></div>
1148 <div class="listingblock">
1149 <div class="content"><!-- Generator: GNU source-highlight 2.9
1150 by Lorenzo Bettini
1151 http://www.lorenzobettini.it
1152 http://www.gnu.org/software/src-highlite -->
1153 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>teeth<span style="color: #990000">,</span> <span style="color: #990000">:</span>singular <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"tooth"</span>
1154 </tt></pre></div></div>
1155 <div class="admonitionblock">
1156 <table><tr>
1157 <td class="icon">
1158 <img src="./images/icons/tip.png" alt="Tip" />
1159 </td>
1160 <td class="content">Depending on the other code in your application, you may prefer to add additional rules to the <tt>Inflector</tt> class instead.</td>
1161 </tr></table>
1162 </div>
1163 <h4 id="_using_requirements">3.7.2. Using :requirements</h4>
1164 <div class="para"><p>You an use the <tt>:requirements</tt> option in a RESTful route to impose a format on the implied <tt>:id</tt> parameter in the singular routes. For example:</p></div>
1165 <div class="listingblock">
1166 <div class="content"><!-- Generator: GNU source-highlight 2.9
1167 by Lorenzo Bettini
1168 http://www.lorenzobettini.it
1169 http://www.gnu.org/software/src-highlite -->
1170 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>requirements <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span><span style="color: #990000">:</span>id <span style="color: #990000">=&gt;</span> <span style="color: #FF6600">/[A-Z][A-Z][0-9]+/</span><span style="color: #FF0000">}</span>
1171 </tt></pre></div></div>
1172 <div class="para"><p>This declaration constrains the <tt>:id</tt> parameter to match the supplied regular expression. So, in this case, <tt>/photos/1</tt> would no longer be recognized by this route, but <tt>/photos/RR27</tt> would.</p></div>
1173 <h4 id="_using_conditions">3.7.3. Using :conditions</h4>
1174 <div class="para"><p>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.)</p></div>
1175 <h4 id="_using_as">3.7.4. Using :as</h4>
1176 <div class="para"><p>The <tt>:as</tt> option lets you override the normal naming for the actual generated paths. For example:</p></div>
1177 <div class="listingblock">
1178 <div class="content"><!-- Generator: GNU source-highlight 2.9
1179 by Lorenzo Bettini
1180 http://www.lorenzobettini.it
1181 http://www.gnu.org/software/src-highlite -->
1182 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>as <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"images"</span>
1183 </tt></pre></div></div>
1184 <div class="para"><p>will recognize incoming URLs containing <tt>image</tt> but route the requests to the Photos controller:</p></div>
1185 <div class="tableblock">
1186 <table rules="all"
1187 frame="hsides"
1188 cellspacing="0" cellpadding="4">
1189 <col width="125" />
1190 <col width="182" />
1191 <col width="137" />
1192 <col width="102" />
1193 <col width="502" />
1194 <thead>
1195   <tr>
1196     <th align="left">
1197     HTTP verb
1198     </th>
1199     <th align="left">
1200     URL
1201     </th>
1202     <th align="left">
1203     controller
1204     </th>
1205     <th align="left">
1206     action
1207     </th>
1208     <th align="left">
1209     used for
1210     </th>
1211   </tr>
1212 </thead>
1213 <tbody valign="top">
1214   <tr>
1215     <td align="left">
1216     GET
1217     </td>
1218     <td align="left">
1219     /images
1220     </td>
1221     <td align="left">
1222     Photos
1223     </td>
1224     <td align="left">
1225     index
1226     </td>
1227     <td align="left">
1228     display a list of all photos
1229     </td>
1230   </tr>
1231   <tr>
1232     <td align="left">
1233     GET
1234     </td>
1235     <td align="left">
1236     /images/new
1237     </td>
1238     <td align="left">
1239     Photos
1240     </td>
1241     <td align="left">
1242     new
1243     </td>
1244     <td align="left">
1245     return an HTML form for creating a new photo
1246     </td>
1247   </tr>
1248   <tr>
1249     <td align="left">
1250     POST
1251     </td>
1252     <td align="left">
1253     /images
1254     </td>
1255     <td align="left">
1256     Photos
1257     </td>
1258     <td align="left">
1259     create
1260     </td>
1261     <td align="left">
1262     create a new photo
1263     </td>
1264   </tr>
1265   <tr>
1266     <td align="left">
1267     GET
1268     </td>
1269     <td align="left">
1270     /images/1
1271     </td>
1272     <td align="left">
1273     Photos
1274     </td>
1275     <td align="left">
1276     show
1277     </td>
1278     <td align="left">
1279     display a specific photo
1280     </td>
1281   </tr>
1282   <tr>
1283     <td align="left">
1284     GET
1285     </td>
1286     <td align="left">
1287     /images/1/edit
1288     </td>
1289     <td align="left">
1290     Photos
1291     </td>
1292     <td align="left">
1293     edit
1294     </td>
1295     <td align="left">
1296     return an HTML form for editing a photo
1297     </td>
1298   </tr>
1299   <tr>
1300     <td align="left">
1301     PUT
1302     </td>
1303     <td align="left">
1304     /images/1
1305     </td>
1306     <td align="left">
1307     Photos
1308     </td>
1309     <td align="left">
1310     update
1311     </td>
1312     <td align="left">
1313     update a specific photo
1314     </td>
1315   </tr>
1316   <tr>
1317     <td align="left">
1318     DELETE
1319     </td>
1320     <td align="left">
1321     /images/1
1322     </td>
1323     <td align="left">
1324     Photos
1325     </td>
1326     <td align="left">
1327     destroy
1328     </td>
1329     <td align="left">
1330     delete a specific photo
1331     </td>
1332   </tr>
1333 </tbody>
1334 </table>
1335 </div>
1336 <div class="admonitionblock">
1337 <table><tr>
1338 <td class="icon">
1339 <img src="./images/icons/note.png" alt="Note" />
1340 </td>
1341 <td class="content">The helpers will be generated with the name of the resource, not the path name. So in this case, you'd still get <tt>photos_path</tt>, <tt>new_photo_path</tt>, and so on.</td>
1342 </tr></table>
1343 </div>
1344 <h4 id="_using_path_names">3.7.5. Using :path_names</h4>
1345 <div class="para"><p>The <tt>:path_names</tt> option lets you override the automatically-generated "new" and "edit" segments in URLs:</p></div>
1346 <div class="listingblock">
1347 <div class="content"><!-- Generator: GNU source-highlight 2.9
1348 by Lorenzo Bettini
1349 http://www.lorenzobettini.it
1350 http://www.gnu.org/software/src-highlite -->
1351 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>path_names <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>new <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'make'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>edit <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'change'</span> <span style="color: #FF0000">}</span>
1352 </tt></pre></div></div>
1353 <div class="para"><p>This would cause the routing to recognize URLs such as</p></div>
1354 <div class="listingblock">
1355 <div class="content">
1356 <pre><tt>/photos/make
1357 /photos/1/change</tt></pre>
1358 </div></div>
1359 <div class="admonitionblock">
1360 <table><tr>
1361 <td class="icon">
1362 <img src="./images/icons/note.png" alt="Note" />
1363 </td>
1364 <td class="content">The actual action names aren't changed by this option; the two URLs show would still route to the new and edit actions.</td>
1365 </tr></table>
1366 </div>
1367 <div class="admonitionblock">
1368 <table><tr>
1369 <td class="icon">
1370 <img src="./images/icons/tip.png" alt="Tip" />
1371 </td>
1372 <td class="content">If you find yourself wanting to change this option uniformly for all of your routes, you can set a default in your environment:</td>
1373 </tr></table>
1374 </div>
1375 <div class="listingblock">
1376 <div class="content"><!-- Generator: GNU source-highlight 2.9
1377 by Lorenzo Bettini
1378 http://www.lorenzobettini.it
1379 http://www.gnu.org/software/src-highlite -->
1380 <pre><tt>config<span style="color: #990000">.</span>action_controller<span style="color: #990000">.</span>resources_path_names <span style="color: #990000">=</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>new <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'make'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>edit <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'change'</span> <span style="color: #FF0000">}</span>
1381 </tt></pre></div></div>
1382 <h4 id="_using_path_prefix">3.7.6. Using :path_prefix</h4>
1383 <div class="para"><p>The <tt>:path_prefix</tt> 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:</p></div>
1384 <div class="listingblock">
1385 <div class="content"><!-- Generator: GNU source-highlight 2.9
1386 by Lorenzo Bettini
1387 http://www.lorenzobettini.it
1388 http://www.gnu.org/software/src-highlite -->
1389 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>path_prefix <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'/photographers/:photographer_id'</span>
1390 </tt></pre></div></div>
1391 <div class="para"><p>Routes recognized by this entry would include:</p></div>
1392 <div class="listingblock">
1393 <div class="content">
1394 <pre><tt>/photographers/1/photos/2
1395 /photographers/1/photos</tt></pre>
1396 </div></div>
1397 <div class="admonitionblock">
1398 <table><tr>
1399 <td class="icon">
1400 <img src="./images/icons/note.png" alt="Note" />
1401 </td>
1402 <td class="content">In most cases, it's simpler to recognize URLs of this sort by creating nested resources, as discussed in the next section.</td>
1403 </tr></table>
1404 </div>
1405 <div class="admonitionblock">
1406 <table><tr>
1407 <td class="icon">
1408 <img src="./images/icons/note.png" alt="Note" />
1409 </td>
1410 <td class="content">You can also use <tt>:path_prefix</tt> with non-RESTful routes.</td>
1411 </tr></table>
1412 </div>
1413 <h4 id="_using_name_prefix">3.7.7. Using :name_prefix</h4>
1414 <div class="para"><p>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 <tt>:path_prefix</tt> to map differently. For example:</p></div>
1415 <div class="listingblock">
1416 <div class="content"><!-- Generator: GNU source-highlight 2.9
1417 by Lorenzo Bettini
1418 http://www.lorenzobettini.it
1419 http://www.gnu.org/software/src-highlite -->
1420 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>path_prefix <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'/photographers/:photographer_id'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>name_prefix <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'photographer_'</span>
1421 map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>path_prefix <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'/agencies/:agency_id'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>name_prefix <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'agency_'</span>
1422 </tt></pre></div></div>
1423 <div class="para"><p>This combination will give you route helpers such as <tt>photographer_photos_path</tt> and <tt>agency_edit_photo_path</tt> to use in your code.</p></div>
1424 <div class="admonitionblock">
1425 <table><tr>
1426 <td class="icon">
1427 <img src="./images/icons/note.png" alt="Note" />
1428 </td>
1429 <td class="content">You can also use <tt>:name_prefix</tt> with non-RESTful routes.</td>
1430 </tr></table>
1431 </div>
1432 <h4 id="_using_only_and_except">3.7.8. Using :only and :except</h4>
1433 <div class="para"><p>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 <tt>:only</tt> and <tt>:except</tt> options to fine-tune this behavior. The <tt>:only</tt> option specifies that only certain routes should be generated:</p></div>
1434 <div class="listingblock">
1435 <div class="content"><!-- Generator: GNU source-highlight 2.9
1436 by Lorenzo Bettini
1437 http://www.lorenzobettini.it
1438 http://www.gnu.org/software/src-highlite -->
1439 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">[:</span>index<span style="color: #990000">,</span> <span style="color: #990000">:</span>show<span style="color: #990000">]</span>
1440 </tt></pre></div></div>
1441 <div class="para"><p>With this declaration, a <tt>GET</tt> request to <tt>/photos</tt> would succeed, but a <tt>POST</tt> request to <tt>/photos</tt> (which would ordinarily be routed to the create action) will fail.</p></div>
1442 <div class="para"><p>The <tt>:except</tt> option specifies a route or list of routes that should <em>not</em> be generated:</p></div>
1443 <div class="listingblock">
1444 <div class="content"><!-- Generator: GNU source-highlight 2.9
1445 by Lorenzo Bettini
1446 http://www.lorenzobettini.it
1447 http://www.gnu.org/software/src-highlite -->
1448 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>except <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>destroy
1449 </tt></pre></div></div>
1450 <div class="para"><p>In this case, all of the normal routes except the route for <tt>destroy</tt> (a <tt>DELETE</tt> request to <tt>/photos/<em>id</em></tt>) will be generated.</p></div>
1451 <div class="para"><p>In addition to an action or a list of actions, you can also supply the special symbols <tt>:all</tt> or <tt>:none</tt> to the <tt>:only</tt> and <tt>:except</tt> options.</p></div>
1452 <div class="admonitionblock">
1453 <table><tr>
1454 <td class="icon">
1455 <img src="./images/icons/tip.png" alt="Tip" />
1456 </td>
1457 <td class="content">If your application has many RESTful routes, using <tt>:only</tt> and <tt>:accept</tt> to generate only the routes that you actually need can cut down on memory use and speed up the routing process.</td>
1458 </tr></table>
1459 </div>
1460 <h3 id="_nested_resources">3.8. Nested Resources</h3>
1461 <div class="para"><p>It's common to have resources that are logically children of other resources. For example, suppose your application includes these models:</p></div>
1462 <div class="listingblock">
1463 <div class="content"><!-- Generator: GNU source-highlight 2.9
1464 by Lorenzo Bettini
1465 http://www.lorenzobettini.it
1466 http://www.gnu.org/software/src-highlite -->
1467 <pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Magazine <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
1468   has_many <span style="color: #990000">:</span>ads
1469 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1470
1471 <span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Ad <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
1472   belongs_to <span style="color: #990000">:</span>magazine
1473 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1474 </tt></pre></div></div>
1475 <div class="para"><p>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:</p></div>
1476 <div class="listingblock">
1477 <div class="content"><!-- Generator: GNU source-highlight 2.9
1478 by Lorenzo Bettini
1479 http://www.lorenzobettini.it
1480 http://www.gnu.org/software/src-highlite -->
1481 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>magazines <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>magazine<span style="color: #990000">|</span>
1482   magazine<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>ads
1483 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1484 </tt></pre></div></div>
1485 <div class="para"><p>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:</p></div>
1486 <div class="tableblock">
1487 <table rules="all"
1488 frame="hsides"
1489 cellspacing="0" cellpadding="4">
1490 <col width="125" />
1491 <col width="274" />
1492 <col width="137" />
1493 <col width="102" />
1494 <col width="502" />
1495 <thead>
1496   <tr>
1497     <th align="left">
1498     HTTP verb
1499     </th>
1500     <th align="left">
1501     URL
1502     </th>
1503     <th align="left">
1504     controller
1505     </th>
1506     <th align="left">
1507     action
1508     </th>
1509     <th align="left">
1510     used for
1511     </th>
1512   </tr>
1513 </thead>
1514 <tbody valign="top">
1515   <tr>
1516     <td align="left">
1517     GET
1518     </td>
1519     <td align="left">
1520     /magazines/1/ads
1521     </td>
1522     <td align="left">
1523     Ads
1524     </td>
1525     <td align="left">
1526     index
1527     </td>
1528     <td align="left">
1529     display a list of all ads for a specific magazine
1530     </td>
1531   </tr>
1532   <tr>
1533     <td align="left">
1534     GET
1535     </td>
1536     <td align="left">
1537     /magazines/1/ads/new
1538     </td>
1539     <td align="left">
1540     Ads
1541     </td>
1542     <td align="left">
1543     new
1544     </td>
1545     <td align="left">
1546     return an HTML form for creating a new ad belonging to a specific magazine
1547     </td>
1548   </tr>
1549   <tr>
1550     <td align="left">
1551     POST
1552     </td>
1553     <td align="left">
1554     /magazines/1/ads
1555     </td>
1556     <td align="left">
1557     Ads
1558     </td>
1559     <td align="left">
1560     create
1561     </td>
1562     <td align="left">
1563     create a new ad belonging to a specific magazine
1564     </td>
1565   </tr>
1566   <tr>
1567     <td align="left">
1568     GET
1569     </td>
1570     <td align="left">
1571     /magazines/1/ads/1
1572     </td>
1573     <td align="left">
1574     Ads
1575     </td>
1576     <td align="left">
1577     show
1578     </td>
1579     <td align="left">
1580     display a specific ad belonging to a specific magazine
1581     </td>
1582   </tr>
1583   <tr>
1584     <td align="left">
1585     GET
1586     </td>
1587     <td align="left">
1588     /magazines/1/ads/1/edit
1589     </td>
1590     <td align="left">
1591     Ads
1592     </td>
1593     <td align="left">
1594     edit
1595     </td>
1596     <td align="left">
1597     return an HTML form for editing an ad belonging to a specific magazine
1598     </td>
1599   </tr>
1600   <tr>
1601     <td align="left">
1602     PUT
1603     </td>
1604     <td align="left">
1605     /magazines/1/ads/1
1606     </td>
1607     <td align="left">
1608     Ads
1609     </td>
1610     <td align="left">
1611     update
1612     </td>
1613     <td align="left">
1614     update a specific ad belonging to a specific magazine
1615     </td>
1616   </tr>
1617   <tr>
1618     <td align="left">
1619     DELETE
1620     </td>
1621     <td align="left">
1622     /magazines/1/ads/1
1623     </td>
1624     <td align="left">
1625     Ads
1626     </td>
1627     <td align="left">
1628     destroy
1629     </td>
1630     <td align="left">
1631     delete a specific ad belonging to a specific magazine
1632     </td>
1633   </tr>
1634 </tbody>
1635 </table>
1636 </div>
1637 <div class="para"><p>This will also create routing helpers such as <tt>magazine_ads_url</tt> and <tt>edit_magazine_ad_path</tt>.</p></div>
1638 <h4 id="_using_name_prefix_2">3.8.1. Using :name_prefix</h4>
1639 <div class="para"><p>The <tt>:name_prefix</tt> option overrides the automatically-generated prefix in nested route helpers. For example,</p></div>
1640 <div class="listingblock">
1641 <div class="content"><!-- Generator: GNU source-highlight 2.9
1642 by Lorenzo Bettini
1643 http://www.lorenzobettini.it
1644 http://www.gnu.org/software/src-highlite -->
1645 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>magazines <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>magazine<span style="color: #990000">|</span>
1646   magazine<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>ads<span style="color: #990000">,</span> <span style="color: #990000">:</span>name_prefix <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'periodical'</span>
1647 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1648 </tt></pre></div></div>
1649 <div class="para"><p>This will create routing helpers such as <tt>periodical_ads_url</tt> and <tt>periodical_edit_ad_path</tt>. You can even use <tt>:name_prefix</tt> to suppress the prefix entirely:</p></div>
1650 <div class="listingblock">
1651 <div class="content"><!-- Generator: GNU source-highlight 2.9
1652 by Lorenzo Bettini
1653 http://www.lorenzobettini.it
1654 http://www.gnu.org/software/src-highlite -->
1655 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>magazines <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>magazine<span style="color: #990000">|</span>
1656   magazine<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>ads<span style="color: #990000">,</span> <span style="color: #990000">:</span>name_prefix <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">nil</span></span>
1657 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1658 </tt></pre></div></div>
1659 <div class="para"><p>This will create routing helpers such as <tt>ads_url</tt> and <tt>edit_ad_path</tt>. Note that calling these will still require supplying an article id:</p></div>
1660 <div class="listingblock">
1661 <div class="content"><!-- Generator: GNU source-highlight 2.9
1662 by Lorenzo Bettini
1663 http://www.lorenzobettini.it
1664 http://www.gnu.org/software/src-highlite -->
1665 <pre><tt>ads_url<span style="color: #990000">(</span><span style="color: #009900">@magazine</span><span style="color: #990000">)</span>
1666 edit_ad_path<span style="color: #990000">(</span><span style="color: #009900">@magazine</span><span style="color: #990000">,</span> <span style="color: #009900">@ad</span><span style="color: #990000">)</span>
1667 </tt></pre></div></div>
1668 <h4 id="_using_has_one_and_has_many">3.8.2. Using :has_one and :has_many</h4>
1669 <div class="para"><p>The <tt>:has_one</tt> and <tt>:has_many</tt> options provide a succinct notation for simple nested routes. Use <tt>:has_one</tt> to nest a singleton resource, or <tt>:has_many</tt> to nest a plural resource:</p></div>
1670 <div class="listingblock">
1671 <div class="content"><!-- Generator: GNU source-highlight 2.9
1672 by Lorenzo Bettini
1673 http://www.lorenzobettini.it
1674 http://www.gnu.org/software/src-highlite -->
1675 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>has_one <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>photographer<span style="color: #990000">,</span> <span style="color: #990000">:</span>has_many <span style="color: #990000">=&gt;</span> <span style="color: #990000">[:</span>publications<span style="color: #990000">,</span> <span style="color: #990000">:</span>versions<span style="color: #990000">]</span>
1676 </tt></pre></div></div>
1677 <div class="para"><p>This has the same effect as this set of declarations:</p></div>
1678 <div class="listingblock">
1679 <div class="content"><!-- Generator: GNU source-highlight 2.9
1680 by Lorenzo Bettini
1681 http://www.lorenzobettini.it
1682 http://www.gnu.org/software/src-highlite -->
1683 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>photo<span style="color: #990000">|</span>
1684   photo<span style="color: #990000">.</span>resource <span style="color: #990000">:</span>photographer
1685   photo<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>publications
1686   photo<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>versions
1687 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1688 </tt></pre></div></div>
1689 <h4 id="_limits_to_nesting">3.8.3. Limits to Nesting</h4>
1690 <div class="para"><p>You can nest resources within other nested resources if you like. For example:</p></div>
1691 <div class="listingblock">
1692 <div class="content"><!-- Generator: GNU source-highlight 2.9
1693 by Lorenzo Bettini
1694 http://www.lorenzobettini.it
1695 http://www.gnu.org/software/src-highlite -->
1696 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>publishers <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>publisher<span style="color: #990000">|</span>
1697   publisher<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>magazines <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>magazine<span style="color: #990000">|</span>
1698     magazine<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos
1699   <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1700 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1701 </tt></pre></div></div>
1702 <div class="para"><p>However, without the use of <tt>name_prefix &#8658; nil</tt>, deeply-nested resources quickly become cumbersome. In this case, for example, the application would recognize URLs such as</p></div>
1703 <div class="listingblock">
1704 <div class="content">
1705 <pre><tt>/publishers/1/magazines/2/photos/3</tt></pre>
1706 </div></div>
1707 <div class="para"><p>The corresponding route helper would be <tt>publisher_magazine_photo_url</tt>, requiring you to specify objects at all three levels. Indeed, this situation is confusing enough that a popular <a href="http://weblog.jamisbuck.org/2007/2/5/nesting-resources">article</a> by Jamis Buck proposes a rule of thumb for good Rails design:</p></div>
1708 <div class="para"><p><em>Resources should never be nested more than 1 level deep.</em></p></div>
1709 <h4 id="_shallow_nesting">3.8.4. Shallow Nesting</h4>
1710 <div class="para"><p>The <tt>:shallow</tt> 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 <tt>:id</tt> parameter) will not use the parent path prefix or name prefix. To see what this means, consider this set of routes:</p></div>
1711 <div class="listingblock">
1712 <div class="content"><!-- Generator: GNU source-highlight 2.9
1713 by Lorenzo Bettini
1714 http://www.lorenzobettini.it
1715 http://www.gnu.org/software/src-highlite -->
1716 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>publishers<span style="color: #990000">,</span> <span style="color: #990000">:</span>shallow <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>publisher<span style="color: #990000">|</span>
1717   publisher<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>magazines <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>magazine<span style="color: #990000">|</span>
1718     magazine<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos
1719   <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1720 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1721 </tt></pre></div></div>
1722 <div class="para"><p>This will enable recognition of (among others) these routes:</p></div>
1723 <div class="listingblock">
1724 <div class="content">
1725 <pre><tt>/publishers/1           ==&gt; publisher_path(1)
1726 /publishers/1/magazines ==&gt; publisher_magazines_path(1)
1727 /magazines/2            ==&gt; magazine_path(2)
1728 /magazines/2/photos     ==&gt; magazines_photos_path(2)
1729 /photos/3               ==&gt; photo_path(3)</tt></pre>
1730 </div></div>
1731 <div class="para"><p>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 <tt>:has_one</tt> and <tt>:has_many</tt> options:</p></div>
1732 <div class="listingblock">
1733 <div class="content"><!-- Generator: GNU source-highlight 2.9
1734 by Lorenzo Bettini
1735 http://www.lorenzobettini.it
1736 http://www.gnu.org/software/src-highlite -->
1737 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>publishers<span style="color: #990000">,</span> <span style="color: #990000">:</span>has_many <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>magazines <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>photos <span style="color: #FF0000">}</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>shallow <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span>
1738 </tt></pre></div></div>
1739 <h3 id="_route_generation_from_arrays">3.9. Route Generation from Arrays</h3>
1740 <div class="para"><p>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:</p></div>
1741 <div class="listingblock">
1742 <div class="content"><!-- Generator: GNU source-highlight 2.9
1743 by Lorenzo Bettini
1744 http://www.lorenzobettini.it
1745 http://www.gnu.org/software/src-highlite -->
1746 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>magazines <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>magazine<span style="color: #990000">|</span>
1747   magazine<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>ads
1748 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1749 </tt></pre></div></div>
1750 <div class="para"><p>Rails will generate helpers such as magazine_ad_path that you can use in building links:</p></div>
1751 <div class="listingblock">
1752 <div class="content"><!-- Generator: GNU source-highlight 2.9
1753 by Lorenzo Bettini
1754 http://www.lorenzobettini.it
1755 http://www.gnu.org/software/src-highlite -->
1756 <pre><tt><span style="color: #FF0000">&lt;%= link_to "Ad details", magazine_ad_path(@magazine, @ad) %&gt;</span>
1757 </tt></pre></div></div>
1758 <div class="para"><p>Another way to refer to the same route is with an array of objects:</p></div>
1759 <div class="listingblock">
1760 <div class="content"><!-- Generator: GNU source-highlight 2.9
1761 by Lorenzo Bettini
1762 http://www.lorenzobettini.it
1763 http://www.gnu.org/software/src-highlite -->
1764 <pre><tt><span style="color: #FF0000">&lt;%= link_to "Ad details", [@magazine, @ad] %&gt;</span>
1765 </tt></pre></div></div>
1766 <div class="para"><p>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.</p></div>
1767 <h3 id="_namespaced_resources">3.10. Namespaced Resources</h3>
1768 <div class="para"><p>It's possible to do some quite complex things by combining <tt>:path_prefix</tt> and <tt>:name_prefix</tt>. For example, you can use the combination of these two options to move administrative resources to their own folder in your application:</p></div>
1769 <div class="listingblock">
1770 <div class="content"><!-- Generator: GNU source-highlight 2.9
1771 by Lorenzo Bettini
1772 http://www.lorenzobettini.it
1773 http://www.gnu.org/software/src-highlite -->
1774 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>path_prefix <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'admin'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'admin/photos'</span>
1775 map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>tags<span style="color: #990000">,</span> <span style="color: #990000">:</span>name_prefix <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'admin_photo_'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>path_prefix <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'admin/photos/:photo_id'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'admin/photo_tags'</span>
1776 map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>ratings<span style="color: #990000">,</span> <span style="color: #990000">:</span>name_prefix <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'admin_photo_'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>path_prefix <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'admin/photos/:photo_id'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'admin/photo_ratings'</span>
1777 </tt></pre></div></div>
1778 <div class="para"><p>The good news is that if you find yourself using this level of complexity, you can stop. Rails supports <em>namespaced resources</em> to make placing resources in their own folder a snap. Here's the namespaced version of those same three routes:</p></div>
1779 <div class="listingblock">
1780 <div class="content"><!-- Generator: GNU source-highlight 2.9
1781 by Lorenzo Bettini
1782 http://www.lorenzobettini.it
1783 http://www.gnu.org/software/src-highlite -->
1784 <pre><tt>map<span style="color: #990000">.</span>namespace<span style="color: #990000">(:</span>admin<span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>admin<span style="color: #990000">|</span>
1785         admin<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span>
1786           <span style="color: #990000">:</span>has_many <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>tags<span style="color: #990000">,</span> <span style="color: #990000">:</span>ratings<span style="color: #FF0000">}</span>
1787 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1788 </tt></pre></div></div>
1789 <div class="para"><p>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 <tt>admin_photos_url</tt> that expects to find an <tt>Admin::PhotosController</tt> and that matches <tt>admin/photos</tt>, and <tt>admin_photos_ratings_path</tt> that matches <tt>/admin/photos/<em>photo_id</em>/ratings</tt>, expecting to use <tt>Admin::RatingsController</tt>. Even though you're not specifying <tt>path_prefix</tt> explicitly, the routing code will calculate the appropriate <tt>path_prefix</tt> from the route nesting.</p></div>
1790 <h3 id="_adding_more_restful_actions">3.11. Adding More RESTful Actions</h3>
1791 <div class="para"><p>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).</p></div>
1792 <h4 id="_adding_member_routes">3.11.1. Adding Member Routes</h4>
1793 <div class="para"><p>To add a member route, use the <tt>:member</tt> option:</p></div>
1794 <div class="listingblock">
1795 <div class="content"><!-- Generator: GNU source-highlight 2.9
1796 by Lorenzo Bettini
1797 http://www.lorenzobettini.it
1798 http://www.gnu.org/software/src-highlite -->
1799 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>member <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>preview <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>get <span style="color: #FF0000">}</span>
1800 </tt></pre></div></div>
1801 <div class="para"><p>This will enable Rails to recognize URLs such as <tt>/photos/1/preview</tt> using the GET HTTP verb, and route them to the preview action of the Photos controller. It will also create a <tt>preview_photo</tt> route helper.</p></div>
1802 <div class="para"><p>Within the hash of member routes, each route name specifies the HTTP verb that it will recognize. You can use <tt>:get</tt>, <tt>:put</tt>, <tt>:post</tt>, <tt>:delete</tt>, or <tt>:any</tt> here. You can also specify an array of methods, if you need more than one but you don't want to allow just anything:</p></div>
1803 <div class="listingblock">
1804 <div class="content"><!-- Generator: GNU source-highlight 2.9
1805 by Lorenzo Bettini
1806 http://www.lorenzobettini.it
1807 http://www.gnu.org/software/src-highlite -->
1808 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>member <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>prepare <span style="color: #990000">=&gt;</span> <span style="color: #990000">[:</span>get<span style="color: #990000">,</span> <span style="color: #990000">:</span>post<span style="color: #990000">]</span> <span style="color: #FF0000">}</span>
1809 </tt></pre></div></div>
1810 <h4 id="_adding_collection_routes">3.11.2. Adding Collection Routes</h4>
1811 <div class="para"><p>To add a collection route, use the <tt>:collection</tt> option:</p></div>
1812 <div class="listingblock">
1813 <div class="content"><!-- Generator: GNU source-highlight 2.9
1814 by Lorenzo Bettini
1815 http://www.lorenzobettini.it
1816 http://www.gnu.org/software/src-highlite -->
1817 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>collection <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>search <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>get <span style="color: #FF0000">}</span>
1818 </tt></pre></div></div>
1819 <div class="para"><p>This will enable Rails to recognize URLs such as <tt>/photos/search</tt> using the GET HTTP verb, and route them to the search action of the Photos controller. It will also create a <tt>search_photos</tt> route helper.</p></div>
1820 <div class="para"><p>Just as with member routes, you can specify an array of methods for a collection route:</p></div>
1821 <div class="listingblock">
1822 <div class="content"><!-- Generator: GNU source-highlight 2.9
1823 by Lorenzo Bettini
1824 http://www.lorenzobettini.it
1825 http://www.gnu.org/software/src-highlite -->
1826 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>collection <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>search <span style="color: #990000">=&gt;</span> <span style="color: #990000">[:</span>get<span style="color: #990000">,</span> <span style="color: #990000">:</span>post<span style="color: #990000">]</span> <span style="color: #FF0000">}</span>
1827 </tt></pre></div></div>
1828 <h4 id="_adding_new_routes">3.11.3. Adding New Routes</h4>
1829 <div class="para"><p>To add a new route (one that creates a new resource), use the <tt>:new</tt> option:</p></div>
1830 <div class="listingblock">
1831 <div class="content"><!-- Generator: GNU source-highlight 2.9
1832 by Lorenzo Bettini
1833 http://www.lorenzobettini.it
1834 http://www.gnu.org/software/src-highlite -->
1835 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>new <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>upload <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>post <span style="color: #FF0000">}</span>
1836 </tt></pre></div></div>
1837 <div class="para"><p>This will enable Rails to recognize URLs such as <tt>/photos/upload</tt> using the POST HTTP verb, and route them to the upload action of the Photos controller. It will also create a <tt>upload_photos</tt> route helper.</p></div>
1838 <div class="admonitionblock">
1839 <table><tr>
1840 <td class="icon">
1841 <img src="./images/icons/tip.png" alt="Tip" />
1842 </td>
1843 <td class="content">If you want to redefine the verbs accepted by one of the standard actions, you can do so by explicitly mapping that action. For example:</td>
1844 </tr></table>
1845 </div>
1846 <div class="listingblock">
1847 <div class="content"><!-- Generator: GNU source-highlight 2.9
1848 by Lorenzo Bettini
1849 http://www.lorenzobettini.it
1850 http://www.gnu.org/software/src-highlite -->
1851 <pre><tt>map<span style="color: #990000">.</span>resources <span style="color: #990000">:</span>photos<span style="color: #990000">,</span> <span style="color: #990000">:</span>new <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>new <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>any <span style="color: #FF0000">}</span>
1852 </tt></pre></div></div>
1853 <div class="para"><p>This will allow the new action to be invoked by any request to <tt>photos/new</tt>, no matter what HTTP verb you use.</p></div>
1854 <h4 id="_a_note_of_caution">3.11.4. A Note of Caution</h4>
1855 <div class="para"><p>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 <tt>:member</tt> and <tt>:collection</tt> hashes become a dumping-ground, RESTful routes lose the advantage of easy readability that is one of their strongest points.</p></div>
1856 </div>
1857 <h2 id="_regular_routes_2">4. Regular Routes</h2>
1858 <div class="sectionbody">
1859 <div class="para"><p>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.</p></div>
1860 <div class="para"><p>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 <em>when possible</em>, 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.</p></div>
1861 <h3 id="_bound_parameters">4.1. Bound Parameters</h3>
1862 <div class="para"><p>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: <tt>:controller</tt> maps to the name of a controller in your application, and <tt>:action</tt> maps to the name of an action within that controller. For example, consider one of the default Rails routes:</p></div>
1863 <div class="listingblock">
1864 <div class="content"><!-- Generator: GNU source-highlight 2.9
1865 by Lorenzo Bettini
1866 http://www.lorenzobettini.it
1867 http://www.gnu.org/software/src-highlite -->
1868 <pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':controller/:action/:id'</span>
1869 </tt></pre></div></div>
1870 <div class="para"><p>If an incoming request of <tt>/photos/show/1</tt> is processed by this route (because it hasn't matched any previous route in the file), then the result will be to invoke the <tt>show</tt> action of the <tt>Photos</tt> controller, and to make the final parameter (1) available as <tt>params[:id]</tt>.</p></div>
1871 <h3 id="_wildcard_components">4.2. Wildcard Components</h3>
1872 <div class="para"><p>You can set up as many wildcard symbols within a regular route as you like. Anything other than <tt>:controller</tt> or <tt>:action</tt> will be available to the matching action as part of the params hash. So, if you set up this route:</p></div>
1873 <div class="listingblock">
1874 <div class="content"><!-- Generator: GNU source-highlight 2.9
1875 by Lorenzo Bettini
1876 http://www.lorenzobettini.it
1877 http://www.gnu.org/software/src-highlite -->
1878 <pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':controller/:action/:id/:user_id'</span>
1879 </tt></pre></div></div>
1880 <div class="para"><p>An incoming URL of <tt>/photos/show/1/2</tt> will be dispatched to the <tt>show</tt> action of the <tt>Photos</tt> controller. <tt>params[:id]</tt> will be set to 1, and <tt>params[:user_id]</tt> will be set to 2.</p></div>
1881 <h3 id="_static_text">4.3. Static Text</h3>
1882 <div class="para"><p>You can specify static text when creating a route. In this case, the static text is used only for matching the incoming requests:</p></div>
1883 <div class="listingblock">
1884 <div class="content"><!-- Generator: GNU source-highlight 2.9
1885 by Lorenzo Bettini
1886 http://www.lorenzobettini.it
1887 http://www.gnu.org/software/src-highlite -->
1888 <pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':controller/:action/:id/with_user/:user_id'</span>
1889 </tt></pre></div></div>
1890 <div class="para"><p>This route would respond to URLs such as <tt>/photos/show/1/with_user/2</tt>.</p></div>
1891 <h3 id="_querystring_parameters">4.4. Querystring Parameters</h3>
1892 <div class="para"><p>Rails routing automatically picks up querystring parameters and makes them available in the <tt>params</tt> hash. For example, with this route:</p></div>
1893 <div class="listingblock">
1894 <div class="content"><!-- Generator: GNU source-highlight 2.9
1895 by Lorenzo Bettini
1896 http://www.lorenzobettini.it
1897 http://www.gnu.org/software/src-highlite -->
1898 <pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':controller/:action/:id'</span>
1899 </tt></pre></div></div>
1900 <div class="para"><p>An incoming URL of <tt>/photos/show/1?user_id=2</tt> will be dispatched to the <tt>show</tt> action of the <tt>Photos</tt> controller. <tt>params[:id]</tt> will be set to 1, and <tt>params[:user_id]</tt> will be equal to 2.</p></div>
1901 <h3 id="_defining_defaults">4.5. Defining Defaults</h3>
1902 <div class="para"><p>You do not need to explicitly use the <tt>:controller</tt> and <tt>:action</tt> symbols within a route. You can supply defaults for these two parameters in a hash:</p></div>
1903 <div class="listingblock">
1904 <div class="content"><!-- Generator: GNU source-highlight 2.9
1905 by Lorenzo Bettini
1906 http://www.lorenzobettini.it
1907 http://www.gnu.org/software/src-highlite -->
1908 <pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">'photo/:id'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'photos'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'show'</span>
1909 </tt></pre></div></div>
1910 <div class="para"><p>With this route, an incoming URL of <tt>/photos/12</tt> would be dispatched to the <tt>show</tt> action within the <tt>Photos</tt> controller.</p></div>
1911 <div class="para"><p>You an also define other defaults in a route by supplying a hash for the <tt>:defaults</tt> option. This even applies to parameters that are not explicitly defined elsewhere in the route. For example:</p></div>
1912 <div class="listingblock">
1913 <div class="content"><!-- Generator: GNU source-highlight 2.9
1914 by Lorenzo Bettini
1915 http://www.lorenzobettini.it
1916 http://www.gnu.org/software/src-highlite -->
1917 <pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">'photo/:id'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'photos'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'show'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>defaults <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>format <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'jpg'</span> <span style="color: #FF0000">}</span>
1918 </tt></pre></div></div>
1919 <div class="para"><p>With this route, an incoming URL of <tt>photos/12</tt> would be dispatched to the <tt>show</tt> action within the <tt>Photos</tt> controller, and <tt>params[:format]</tt> will be set to <tt>jpg</tt>.</p></div>
1920 <h3 id="_named_routes_2">4.6. Named Routes</h3>
1921 <div class="para"><p>Regular routes need not use the <tt>connect</tt> method. You can use any other name here to create a <em>named route</em>. For example,</p></div>
1922 <div class="listingblock">
1923 <div class="content"><!-- Generator: GNU source-highlight 2.9
1924 by Lorenzo Bettini
1925 http://www.lorenzobettini.it
1926 http://www.gnu.org/software/src-highlite -->
1927 <pre><tt>map<span style="color: #990000">.</span>logout <span style="color: #FF0000">'/logout'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'sessions'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'destroy'</span>
1928 </tt></pre></div></div>
1929 <div class="para"><p>This will do two things. First, requests to <tt>/logout</tt> will be sent to the <tt>destroy</tt> method of the <tt>Sessions</tt> controller. Second, Rails will maintain the <tt>logout_path</tt> and <tt>logout_url</tt> helpers for use within your code.</p></div>
1930 <h3 id="_route_requirements">4.7. Route Requirements</h3>
1931 <div class="para"><p>You can use the <tt>:requirements</tt> option to enforce a format for any parameter in a route:</p></div>
1932 <div class="listingblock">
1933 <div class="content"><!-- Generator: GNU source-highlight 2.9
1934 by Lorenzo Bettini
1935 http://www.lorenzobettini.it
1936 http://www.gnu.org/software/src-highlite -->
1937 <pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">'photo/:id'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'photos'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'show'</span><span style="color: #990000">,</span>
1938  <span style="color: #990000">:</span>requirements <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>id <span style="color: #990000">=&gt;</span> <span style="color: #FF6600">/[A-Z]\d{5}/</span> <span style="color: #FF0000">}</span>
1939 </tt></pre></div></div>
1940 <div class="para"><p>This route would respond to URLs such as <tt>/photo/A12345</tt>. You can more succinctly express the same route this way:</p></div>
1941 <div class="listingblock">
1942 <div class="content"><!-- Generator: GNU source-highlight 2.9
1943 by Lorenzo Bettini
1944 http://www.lorenzobettini.it
1945 http://www.gnu.org/software/src-highlite -->
1946 <pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">'photo/:id'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'photos'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'show'</span><span style="color: #990000">,</span>
1947   <span style="color: #990000">:</span>id <span style="color: #990000">=&gt;</span> <span style="color: #FF6600">/[A-Z]\d{5}/</span>
1948 </tt></pre></div></div>
1949 <h3 id="_route_conditions">4.8. Route Conditions</h3>
1950 <div class="para"><p>Route conditions (introduced with the <tt>:conditions</tt> option) are designed to implement restrictions on routes. Currently, the only supported restriction is <tt>:method</tt>:</p></div>
1951 <div class="listingblock">
1952 <div class="content"><!-- Generator: GNU source-highlight 2.9
1953 by Lorenzo Bettini
1954 http://www.lorenzobettini.it
1955 http://www.gnu.org/software/src-highlite -->
1956 <pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">'photo/:id'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'photos'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'show'</span><span style="color: #990000">,</span>
1957  <span style="color: #990000">:</span>conditions <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>method <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>get <span style="color: #FF0000">}</span>
1958 </tt></pre></div></div>
1959 <div class="para"><p>As with conditions in RESTful routes, you can specify <tt>:get</tt>, <tt>:post</tt>, <tt>:put</tt>, <tt>:delete</tt>, or <tt>:any</tt> for the acceptable method.</p></div>
1960 <h3 id="_route_globbing">4.9. Route Globbing</h3>
1961 <div class="para"><p>Route globbing is a way to specify that a particular parameter (which must be the last parameter in the route) should be matched to all the remaining parts of a route. For example</p></div>
1962 <div class="listingblock">
1963 <div class="content"><!-- Generator: GNU source-highlight 2.9
1964 by Lorenzo Bettini
1965 http://www.lorenzobettini.it
1966 http://www.gnu.org/software/src-highlite -->
1967 <pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">'photo/*other'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'photos'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'unknown'</span><span style="color: #990000">,</span>
1968 </tt></pre></div></div>
1969 <div class="para"><p>This route would match <tt>photo/12</tt> or <tt>/photo/long/path/to/12</tt> equally well, creating an array of path segments as the value of <tt>params[:other]</tt>.</p></div>
1970 <h3 id="_route_options">4.10. Route Options</h3>
1971 <div class="para"><p>You can use <tt>:with_options</tt> to simplify defining groups of similar routes:</p></div>
1972 <div class="listingblock">
1973 <div class="content"><!-- Generator: GNU source-highlight 2.9
1974 by Lorenzo Bettini
1975 http://www.lorenzobettini.it
1976 http://www.gnu.org/software/src-highlite -->
1977 <pre><tt>map<span style="color: #990000">.</span>with_options <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'photo'</span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>photo<span style="color: #990000">|</span>
1978   photo<span style="color: #990000">.</span>list <span style="color: #FF0000">''</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'index'</span>
1979   photo<span style="color: #990000">.</span>delete <span style="color: #FF0000">':id/delete'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'delete'</span>
1980   photo<span style="color: #990000">.</span>edit <span style="color: #FF0000">':id/edit'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'edit'</span>
1981 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
1982 </tt></pre></div></div>
1983 <div class="para"><p>The importance of <tt>map.with_options</tt> has declined with the introduction of RESTful routes.</p></div>
1984 </div>
1985 <h2 id="_formats_and_respond_to">5. Formats and respond_to</h2>
1986 <div class="sectionbody">
1987 <div class="para"><p>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 <tt>:format</tt> parameter in the route.</p></div>
1988 <div class="para"><p>For instance, consider the second of the default routes in the boilerplate <tt>routes.rb</tt> file:</p></div>
1989 <div class="listingblock">
1990 <div class="content"><!-- Generator: GNU source-highlight 2.9
1991 by Lorenzo Bettini
1992 http://www.lorenzobettini.it
1993 http://www.gnu.org/software/src-highlite -->
1994 <pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':controller/:action/:id.:format'</span>
1995 </tt></pre></div></div>
1996 <div class="para"><p>This route matches requests such as <tt>/photo/edit/1.xml</tt> or <tt>/photo/show/2.rss</tt>. Within the appropriate action code, you can issue different responses depending on the requested format:</p></div>
1997 <div class="listingblock">
1998 <div class="content"><!-- Generator: GNU source-highlight 2.9
1999 by Lorenzo Bettini
2000 http://www.lorenzobettini.it
2001 http://www.gnu.org/software/src-highlite -->
2002 <pre><tt>respond_to <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>format<span style="color: #990000">|</span>
2003   format<span style="color: #990000">.</span>html <span style="font-style: italic"><span style="color: #9A1900"># return the default template for HTML</span></span>
2004   format<span style="color: #990000">.</span>xml <span style="color: #FF0000">{</span> render <span style="color: #990000">:</span>xml <span style="color: #990000">=&gt;</span> <span style="color: #009900">@photo</span><span style="color: #990000">.</span>to_xml <span style="color: #FF0000">}</span>
2005 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
2006 </tt></pre></div></div>
2007 <h3 id="_specifying_the_format_with_an_http_header">5.1. Specifying the Format with an HTTP Header</h3>
2008 <div class="para"><p>If there is no <tt>:format</tt> parameter in the route, Rails will automatically look at the HTTP Accept header to determine the desired format.</p></div>
2009 <h3 id="_recognized_mime_types">5.2. Recognized MIME types</h3>
2010 <div class="para"><p>By default, Rails recognizes <tt>html</tt>, <tt>text</tt>, <tt>json</tt>, <tt>csv</tt>, <tt>xml</tt>, <tt>rss</tt>, <tt>atom</tt>, and <tt>yaml</tt> as acceptable response types. If you need types beyond this, you can register them in your environment:</p></div>
2011 <div class="listingblock">
2012 <div class="content"><!-- Generator: GNU source-highlight 2.9
2013 by Lorenzo Bettini
2014 http://www.lorenzobettini.it
2015 http://www.gnu.org/software/src-highlite -->
2016 <pre><tt>Mime<span style="color: #990000">::</span>Type<span style="color: #990000">.</span>register <span style="color: #FF0000">"image/jpg"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>jpg
2017 </tt></pre></div></div>
2018 </div>
2019 <h2 id="_the_default_routes">6. The Default Routes</h2>
2020 <div class="sectionbody">
2021 <div class="para"><p>When you create a new Rails application, <tt>routes.rb</tt> is initialized with two default routes:</p></div>
2022 <div class="listingblock">
2023 <div class="content"><!-- Generator: GNU source-highlight 2.9
2024 by Lorenzo Bettini
2025 http://www.lorenzobettini.it
2026 http://www.gnu.org/software/src-highlite -->
2027 <pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':controller/:action/:id'</span>
2028 map<span style="color: #990000">.</span>connect <span style="color: #FF0000">':controller/:action/:id.:format'</span>
2029 </tt></pre></div></div>
2030 <div class="para"><p>These routes provide reasonable defaults for many URLs, if you're not using RESTful routing.</p></div>
2031 <div class="admonitionblock">
2032 <table><tr>
2033 <td class="icon">
2034 <img src="./images/icons/note.png" alt="Note" />
2035 </td>
2036 <td class="content">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.</td>
2037 </tr></table>
2038 </div>
2039 </div>
2040 <h2 id="_the_empty_route">7. The Empty Route</h2>
2041 <div class="sectionbody">
2042 <div class="para"><p>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 <tt>http://example.com</tt> or <tt>http://example.com/</tt> will be handled by the empty route.</p></div>
2043 <h3 id="_using_map_root">7.1. Using map.root</h3>
2044 <div class="para"><p>The preferred way to set up the empty route is with the <tt>map.root</tt> command:</p></div>
2045 <div class="listingblock">
2046 <div class="content"><!-- Generator: GNU source-highlight 2.9
2047 by Lorenzo Bettini
2048 http://www.lorenzobettini.it
2049 http://www.gnu.org/software/src-highlite -->
2050 <pre><tt>map<span style="color: #990000">.</span>root <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"pages"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"main"</span>
2051 </tt></pre></div></div>
2052 <div class="para"><p>The use of the <tt>root</tt> method tells Rails that this route applies to requests for the root of the site.</p></div>
2053 <div class="para"><p>For better readability, you can specify an already-created route in your call to <tt>map.root</tt>:</p></div>
2054 <div class="listingblock">
2055 <div class="content"><!-- Generator: GNU source-highlight 2.9
2056 by Lorenzo Bettini
2057 http://www.lorenzobettini.it
2058 http://www.gnu.org/software/src-highlite -->
2059 <pre><tt>map<span style="color: #990000">.</span>index <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"pages"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"main"</span>
2060 map<span style="color: #990000">.</span>root <span style="color: #990000">:</span>index
2061 </tt></pre></div></div>
2062 <div class="para"><p>Because of the top-down processing of the file, the named route must be specified <em>before</em> the call to <tt>map.root</tt>.</p></div>
2063 <h3 id="_connecting_the_empty_string">7.2. Connecting the Empty String</h3>
2064 <div class="para"><p>You can also specify an empty route by explicitly connecting the empty string:</p></div>
2065 <div class="listingblock">
2066 <div class="content"><!-- Generator: GNU source-highlight 2.9
2067 by Lorenzo Bettini
2068 http://www.lorenzobettini.it
2069 http://www.gnu.org/software/src-highlite -->
2070 <pre><tt>map<span style="color: #990000">.</span>connect <span style="color: #FF0000">''</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"pages"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"main"</span>
2071 </tt></pre></div></div>
2072 <div class="admonitionblock">
2073 <table><tr>
2074 <td class="icon">
2075 <img src="./images/icons/tip.png" alt="Tip" />
2076 </td>
2077 <td class="content">If the empty route does not seem to be working in your application, make sure that you have deleted the file <tt>public/index.html</tt> from your Rails tree.</td>
2078 </tr></table>
2079 </div>
2080 </div>
2081 <h2 id="_inspecting_and_testing_routes">8. Inspecting and Testing Routes</h2>
2082 <div class="sectionbody">
2083 <div class="para"><p>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.</p></div>
2084 <h3 id="_seeing_existing_routes_with_rake">8.1. Seeing Existing Routes with rake</h3>
2085 <div class="para"><p>If you want a complete list of all of the available routes in your application, run the <tt>rake routes</tt> command. This will dump all of your routes to the console, in the same order that they appear in <tt>routes.rb</tt>. For each route, you'll see:</p></div>
2086 <div class="ilist"><ul>
2087 <li>
2088 <p>
2089 The route name (if any)
2090 </p>
2091 </li>
2092 <li>
2093 <p>
2094 The HTTP verb used (if the route doesn't respond to all verbs)
2095 </p>
2096 </li>
2097 <li>
2098 <p>
2099 The URL pattern
2100 </p>
2101 </li>
2102 <li>
2103 <p>
2104 The routing parameters that will be generated by this URL
2105 </p>
2106 </li>
2107 </ul></div>
2108 <div class="para"><p>For example, here's a small section of the <tt>rake routes</tt> output for a RESTful route:</p></div>
2109 <div class="listingblock">
2110 <div class="content">
2111 <pre><tt>          users GET  /users          {:controller=&gt;"users", :action=&gt;"index"}
2112 formatted_users GET  /users.:format  {:controller=&gt;"users", :action=&gt;"index"}
2113                 POST /users          {:controller=&gt;"users", :action=&gt;"create"}
2114                 POST /users.:format  {:controller=&gt;"users", :action=&gt;"create"}</tt></pre>
2115 </div></div>
2116 <div class="admonitionblock">
2117 <table><tr>
2118 <td class="icon">
2119 <img src="./images/icons/tip.png" alt="Tip" />
2120 </td>
2121 <td class="content">You'll find that the output from <tt>rake routes</tt> is much more readable if you widen your terminal window until the output lines don't wrap.</td>
2122 </tr></table>
2123 </div>
2124 <h3 id="_testing_routes">8.2. Testing Routes</h3>
2125 <div class="para"><p>Routes should be included in your testing strategy (just like the rest of your application). Rails offers three <a href="http://api.rubyonrails.com/classes/ActionController/Assertions/RoutingAssertions.html">built-in assertions</a> designed to make testing routes simpler:</p></div>
2126 <div class="ilist"><ul>
2127 <li>
2128 <p>
2129 <tt>assert_generates</tt>
2130 </p>
2131 </li>
2132 <li>
2133 <p>
2134 <tt>assert_recognizes</tt>
2135 </p>
2136 </li>
2137 <li>
2138 <p>
2139 <tt>assert_routing</tt>
2140 </p>
2141 </li>
2142 </ul></div>
2143 <h4 id="_the_tt_assert_generates_tt_assertion">8.2.1. The <tt>assert_generates</tt> Assertion</h4>
2144 <div class="para"><p>Use <tt>assert_generates</tt> to assert that a particular set of options generate a particular path. You can use this with default routes or custom routes</p></div>
2145 <div class="listingblock">
2146 <div class="content"><!-- Generator: GNU source-highlight 2.9
2147 by Lorenzo Bettini
2148 http://www.lorenzobettini.it
2149 http://www.gnu.org/software/src-highlite -->
2150 <pre><tt>assert_generates <span style="color: #FF0000">"/photos/1"</span><span style="color: #990000">,</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"photos"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"show"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>id <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"1"</span> <span style="color: #FF0000">}</span>
2151 assert_generates <span style="color: #FF0000">"/about"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"pages"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"about"</span>
2152 </tt></pre></div></div>
2153 <h4 id="_the_tt_assert_recognizes_tt_assertion">8.2.2. The <tt>assert_recognizes</tt> Assertion</h4>
2154 <div class="para"><p>The <tt>assert_recognizes</tt> assertion is the inverse of <tt>assert_generates</tt>. It asserts that Rails recognizes the given path and routes it to a particular spot in your application.</p></div>
2155 <div class="listingblock">
2156 <div class="content"><!-- Generator: GNU source-highlight 2.9
2157 by Lorenzo Bettini
2158 http://www.lorenzobettini.it
2159 http://www.gnu.org/software/src-highlite -->
2160 <pre><tt>assert_recognizes <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"photos"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"show"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>id <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"1"</span> <span style="color: #FF0000">}</span><span style="color: #990000">,</span> <span style="color: #FF0000">"/photos/1"</span>
2161 </tt></pre></div></div>
2162 <div class="para"><p>You can supply a <tt>:method</tt> argument to specify the HTTP verb:</p></div>
2163 <div class="listingblock">
2164 <div class="content"><!-- Generator: GNU source-highlight 2.9
2165 by Lorenzo Bettini
2166 http://www.lorenzobettini.it
2167 http://www.gnu.org/software/src-highlite -->
2168 <pre><tt>assert_recognizes <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"photos"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"create"</span> <span style="color: #FF0000">}</span><span style="color: #990000">,</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>path <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"photos"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>method <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>post <span style="color: #FF0000">}</span>
2169 </tt></pre></div></div>
2170 <div class="para"><p>You can also use the RESTful helpers to test recognition of a RESTful route:</p></div>
2171 <div class="listingblock">
2172 <div class="content"><!-- Generator: GNU source-highlight 2.9
2173 by Lorenzo Bettini
2174 http://www.lorenzobettini.it
2175 http://www.gnu.org/software/src-highlite -->
2176 <pre><tt>assert_recognizes new_photo_url<span style="color: #990000">,</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>path <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"photos"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>method <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>post <span style="color: #FF0000">}</span>
2177 </tt></pre></div></div>
2178 <h4 id="_the_tt_assert_routing_tt_assertion">8.2.3. The <tt>assert_routing</tt> Assertion</h4>
2179 <div class="para"><p>The <tt>assert_routing</tt> assertion checks the route both ways: it tests that the path generates the options, and that the options generate the path. Thus, it combines the functions of <tt>assert_generates</tt> and <tt>assert_recognizes</tt>.</p></div>
2180 <div class="listingblock">
2181 <div class="content"><!-- Generator: GNU source-highlight 2.9
2182 by Lorenzo Bettini
2183 http://www.lorenzobettini.it
2184 http://www.gnu.org/software/src-highlite -->
2185 <pre><tt>assert_routing <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>path <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"photos"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>method <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>post <span style="color: #FF0000">}</span><span style="color: #990000">,</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"photos"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"create"</span> <span style="color: #FF0000">}</span>
2186 </tt></pre></div></div>
2187 </div>
2188 <h2 id="_changelog">9. Changelog</h2>
2189 <div class="sectionbody">
2190 <div class="para"><p><a href="http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/3">Lighthouse ticket</a></p></div>
2191 <div class="ilist"><ul>
2192 <li>
2193 <p>
2194 October 4, 2008: Added additional detail on specifying verbs for resource member/collection routes , by <a href="../authors.html#mgunderloy">Mike Gunderloy</a>
2195 </p>
2196 </li>
2197 <li>
2198 <p>
2199 September 23, 2008: Added section on namespaced controllers and routing, by <a href="../authors.html#mgunderloy">Mike Gunderloy</a>
2200 </p>
2201 </li>
2202 <li>
2203 <p>
2204 September 10, 2008: initial version by <a href="../authors.html#mgunderloy">Mike Gunderloy</a>
2205 </p>
2206 </li>
2207 </ul></div>
2208 </div>
2209
2210                 </div>
2211         </div>
2212 </body>
2213 </html>