Beginners Tutorial: Routing in Rails 2.0 (with REST) - Part 2 of n

Part 3

Thank you to all of you who took the time to give me feedback on part 1. Most of the feedback was positive. A friend of mine suggested that I drop the sound effects and stick to the subject matter, I graciously accepted his advice. Therefore this post should have a better fact to fluff ratio than the previous one. On that note, let’s begin…

Part 2

In part 1 we learnt that the routing system has two main functions:
• Interpreting a request URL
• Generating a request URL
Rails uses the same routing rule to interpret a URL and to generate a URL.
Note that routing rules are often called routes, I will use the terms interchangeably.

Now we will start fixing our music_store application from part 1.

Experiment 2.1 – Setting up the ‘empty route’ to recognise and generate a default page

Please set your system environment up so that we can continue from where we left of at the end of part 1. Make sure the web server is running.

The aim of this experiment if to set the app\views\albums\index.html.erb page as the ‘default page’. Think of this as defining a type of welcome page. Do not confuse this notion of setting a default page with the default route – these ideas are very different, the default route will be discussed in another post.

Rails sidetrack: By default controllers render the view that has the same name of the action invoked. If we call the index action (method) on the albums_controller, it will render the view named index.html.erb in the app\views\albums folder. Similarly calling the show action will result in the show.html.erb view being rendered.

The index page will be shown if we can get Rails to instantiate an albums_controller and then invoke the index action on it. What we want to say is something like:

Rails, when you get http://localhost:3000/
Instantiate controller “albums_controller”
Invoke action “index”

If we say this, there will be a problem when we deploy our application. We would then have to replace localhost with our sites domain name. To avoid this we can assume an implicit domain name. Therefore when defining routes we do not include our applications domain. Instead of saying http://localhost:3000/Albums we could simply say Albums. Similarly, we don’t use http://localhost:3000/, instead we use ‘’. This (‘’) is called the empty URL.

Side note: The term URL can refer to the fully qualified URL or just the path from after the root domain, it depends on the context.

Using the empty URL we can say something like:

Rails, when you get ‘’
Instantiate controller “albums_controller”
Invoke action “index”

Rails is pretty smart, therefore we use “albums” instead of “albums_controller”.
Taking one step closer to the actual code we get

Rails, when you get ‘’
:controller => “albums”
:action => “index”

The last two lines are (just about) lines of Ruby code. That is the Ruby code which forms part of the Rails DSL for defining routing rules. What we have just defined are referred to as the bounded parameters e.g. (:controller => “albums_controller”, :action => “index”).

To complete our route definition we need to connect the empty URL to the bounded parameters. This is how that is done in the config\routs.rb file:

ActionController::Routing::Routes.draw do |map|
  map.connect('', {:controller => "albums", :action => "index"})
end

Caution: Do not expect the music_store site to work now, there is more work to be done before it is fixed.

Let’s neaten up our Ruby code:

We have a method call on the map object which has two parameters, a string and a hash table.
We can get rid of the outer brackets because Ruby does not require them.
As the hash table is the last parameter; Ruby does not require the curly braces.
Now we have this clean version

:map.connect '', :controller => "albums", :action => "index"

Fire up the IRB to see if our route is there (we did this in part one).

C:\InstantRails-2.0-win\rails_apps\music_store>ruby script\console

Loading development environment (Rails 2.0.2)

>> rts = ActionController::Routing::Routes

--- output ---

>>

puts rts.routes

ANY    /              {:action=>"index", :controller=>"albums"}

This is what we are looking at:
ANY – this means it does not matter if the request is a GET or a POST
/ - This is the root domain (the empty URL)
{:action=>”index”, :controller=>”albums”} – Shows which controller and action is connected to the URL.

Read it like this: When an empty URL is received the index action will be called on the albums controller.

As you may recall, the routing system has two main functions. These are interpreting a URL and generating a URL. It does this using the routes defined within the routes.rb file. We will now use the IRB to interpret and generate URLs.

Start up the IRB; if you are not in it already.
Note your Rails server should also be running at this point.

C:\InstantRails-2.0-win\rails_apps\music_store>ruby script\console

Loading development environment (Rails 2.0.2)

>> rts = ActionController::Routing::Routes

--- output ---

>> rts.recognize_path("/")

=> {:action=>"index", :controller=>"albums"}

>> rts.recognize_path("")

=> {:action=>"index", :controller=>"albums"}

This shows us how the routing system would interpret these URLs. We can see that “/” and “” are both interpreted the same – they are both the empty URL.

Now lets test the URL generation

>> rts.generate(:controller=>"albums",:action=>"index")

=> "/"

The routing system found where we had defined an albums controller and the index action, it then returned the connected URL – which was the empty URL.

This completes experiment 2.1. as we have defined a route that allows the routing system to generate and interpret an empty URL.

Note that the actual site will not work at this point. We still need to do some troubleshooting on the albums views, we will do that later.

Experiment 2.2. Explore route ordering

In order to explore route ordering, we need a second route. Let us assume we want to map the URL http://localhost:3000/Music to the same albums controller and index action.

Rails, when you get ‘/Music’
Instantiate controller “albums_controller”
Invoke action “index”

Update the routes.rb file to look like this:

ActionController::Routing::Routes.draw do |map|
  map.connect '', :controller => "albums", :action => "index"
  map.connect 'music', :controller => "albums", :action => "index"
end

Now inspect the behaviour of the routing system via the IRB:

C:\InstantRails-2.0-win\rails_apps\music_store>ruby script\console

Loading development environment (Rails 2.0.2)

>> rts = ActionController::Routing::Routes

-- output--

>>

puts rts.routesANY    /      {:action=>"index", :controller=>"albums"}

ANY    /music/                {:action=>"index", :controller=>"albums"}

=> nil

>>

Great, there is the new route. Note that our music URL does not match our folder structure. Therefore a user can not really tell the file structure of a Rails application from the URL.

Test recognize:

>> rts.recognize_path("")

=> {:action=>"index", :controller=>"albums"}

>> rts.recognize_path("/music")

=> {:action=>"index", :controller=>"albums"}

As expected! But now try a generate:

>> rts.generate(:controller=>"albums",:action=>"index")

=> "/"

Notice that the routing system uses the first rule that matches. You should be aware of this. Let’s assume we would rather have the routing system generate a URL with the music prefix. Swap the order of the routes:

ActionController::Routing::Routes.draw do |map|

  map.connect 'music', :controller => "albums", :action => "index"
  map.connect '', :controller => "albums", :action => "index"

end

Now test generate again, remember to exit the IRB first.

?> exit

C:\InstantRails-2.0-win\rails_apps\music_store>ruby script\console

Loading development environment (Rails 2.0.2)

>> rts = ActionController::Routing::Routes

-- output --

>> rts.generate(:controller=>"albums",:action=>"index")

=> "/music"

>>

All good! Ordering explored, experiment completed!

Once again, don’t expect the actual music_store site to work just yet.

Experiment 2.3. Define routes for Add, Show, Edit & Delete

To get our site fixed, we also need to have routes that will allow us to add, show, edit and delete albums. Let’s start with showing a single album.

Show

We want to define a route that will instantiate the albums controller and call the show method. Looking at app\controllers\albums_controller we notice that the show action retrieves an :id field from the params hash table:

  def show
    @album = Album.find(params[:id])

    respond_to do |format|
      format.html # show.html.erb
      format.xml  { render :xml => @album }

    end
  end

Thanks to Rails the params hash table is automatically available to the controller. We just need to make sure the route sets it. Let’s make our route say something like:Rails, when you get ‘music/show’
Instantiate controller “albums”
Invoke action “show”
Add a value to the params hash table with the key being :id and the value being …?

At this stage we do not know which album to show. We can add this to the URL.

Rails, when you get ‘music/show/3’
Instantiate controller “albums”
Invoke action “show”
Add a value to the params hash table with the key being :id and the value being 3

Update routes.rb to look like this:

ActionController::Routing::Routes.draw do |map|

  map.connect 'music', :controller => "albums", :action => "index"
  map.connect '', :controller => "albums", :action => "index"

  map.connect 'music/show/:id', :controller => "albums", :action => "show"

end

The :id symbol is used to pass through the album ID into the albums controller. We could use any symbol, as long as we were consistent in the controller. :id is a convention. :controller and :action must be used, they are the ingredients of some the Rails magic!Next we will delete or destroy an album.

Delete\Destroy

Now we want to say:Rails, when you get ‘music/delete/3’
Instantiate controller “albums”
Invoke action “destroy”
Add a value to the params hash table with the key being :id and the value being 3

Add this to the routes.rb so that we have:

ActionController::Routing::Routes.draw do |map|

  map.connect 'music', :controller => "albums", :action => "index"
  map.connect '', :controller => "albums", :action => "index"
  map.connect 'music/show/:id', :controller => "albums", :action => "show"

  map.connect 'music/delete/:id', :controller => "albums", :action => "destroy"

end

It is very similar to show. Next up we define a route to Edit an album.

Edit

Edit is a two phase process. First we call edit on the controller, this will result in the album being shown. When the user clicks update we will call the update action on the controller. Therefore we need two routes to do an edit. Update your routes.rb file:

ActionController::Routing::Routes.draw do |map|

  map.connect 'music', :controller => "albums", :action => "index"
  map.connect '', :controller => "albums", :action => "index"
  map.connect 'music/show/:id', :controller => "albums", :action => "show"
  map.connect 'music/delete/:id', :controller => "albums", :action => "destroy"

  map.connect 'music/edit/:id', :controller => "albums", :action => "edit"
  map.connect 'music/update/:id', :controller => "albums", :action => "update"

end

Add

To add a new album is very similar to editing an existing album. It is a two phase process. First we call the new action on the albums controller, this will result in the new view being shown the user, this is an a form with empty fields. Once the user has completed the form the user clicks create. At this stage we want to call the albums controller invoking the create action.Edit the routes.rb file to look like this:

ActionController::Routing::Routes.draw do |map|

  map.connect 'music', :controller => "albums", :action => "index"
  map.connect '', :controller => "albums", :action => "index"
  map.connect 'music/show/:id', :controller => "albums", :action => "show"
  map.connect 'music/delete/:id', :controller => "albums", :action => "destroy"
  map.connect 'music/edit/:id', :controller => "albums", :action => "edit"
  map.connect 'music/update/:id', :controller => "albums", :action => "update"

  map.connect 'music/new', :controller => "albums", :action => "new"
  map.connect 'music/create', :controller => "albums", :action => "create"

end

We are creating a new album, there is no need to pass in the :id field. Those are our basic routes.If you have kept up, Named routes and RESTful routing will be simple, a piece of PHP Cake!

Experiment 2.4. Troubleshooting

To get all of this to work in the browser, we need to perform some troubleshooting. As you may recall we set up a route that will show the albums index view if an empty URL is passed in.

To properly test the route, open your browser and navigate to http://localhost:3000/.

What’s this? Our old friend, the about your application window?

To stop this from showing we need to delete this index page.

Delete the music_store\public\index.html page. Refresh your browser and you should see this error:

When using RESTful routing, and named routes, certain helper methods are dynamically generated. The methods are available to the controller and view. When Rails 2.0 performs scaffolding it assumes you are going to use RESTfull routing and therefore the view makes use of these helper methods. The music_store is currently not using named routes, or RESTful routes, therefore the helper methods are not available. Therefore we get the error message: “Undefined method ‘album_path’.

Open the app\views\albums\index.html.erb, it should look as follows:

<h1>Listing albums</h1>

<table>
  <tr>
    <th>Title</th>
    <th>Review</th>
  </tr>

<% for album in @albums %>
  <tr>
    <td><%=h album.title %></td>
    <td><%=h album.review %></td>
    <td><%= link_to 'Show', album %></td>
    <td><%= link_to 'Edit', edit_album_path(album) %></td>
    <td><%= link_to 'Destroy', album, :confirm => 'Are you sure?', :method => :delete %></td>
  </tr>
<% end %>
</table>

<br />

<%= link_to 'New album', new_album_path %>

We can not see the helper method ‘album_path’ as it is being called implicitly by the link to method on line 13, it is Rails magic. If we had to remove this line we would end up with more errors. Remove line 13 and you will get the following error:Replace line 13 (if you removed it), your view should be back to this:

<h1>Listing albums</h1>

<table>
  <tr>
    <th>Title</th>
    <th>Review</th>
  </tr>

<% for album in @albums %>
  <tr>
    <td><%=h album.title %></td>
    <td><%=h album.review %></td>
    <td><%= link_to 'Show', album %></td>
    <td><%= link_to 'Edit', edit_album_path(album) %></td>
    <td><%= link_to 'Destroy', album, :confirm => 'Are you sure?', :method => :delete %></td>
  </tr>
<% end %>
</table>

<br />

<%= link_to 'New album', new_album_path %>

Looking at the view we can see multiple lines where Rails is using RESTful routing methods e.g. edit_album_path(album), new_album_path etc. These are the helper methods that would have been dynamically created had we been using RESTful routes. We are not and therefore we need to explicitly define our own paths.Update your app\views\albums\index.html.erb to look like this:

<h1>Listing albums</h1>

<table>
  <tr>
    <th>Title</th>
    <th>Review</th>
  </tr>

<% for album in @albums %>
  <tr>
    <td><%=h album.title %></td>
    <td><%=h album.review %></td>
    <td><%= link_to 'Show', :controller => "albums", :action => "show", :id => album.id  %></td>
    <td><%= link_to 'Edit', :controller => "albums", :action => "edit", :id => album.id %></td>
    <td><%= link_to 'Destroy', {:controller => "albums", :action => "destroy", :id => album.id}, :confirm => 'Are you sure?' %></td>
  </tr>
<% end %>
</table>

<br /> 

<%= link_to 'New album', :controller => "albums", :action => "new" %>

Now you should be able to see the albums index page in the browser!
Either with: http://localhost:3000/music or http://localhost:3000/.

Unfortunately there is still more troubleshooting to be done. If you click on a link, you should find your application crashes. This is due to Rails using RESTfull calls throughout. Make the albums show.html.erb look like this:

<p>
  <b>Title:</b>
  <%=h @album.title %>
</p>

<p>
  <b>Review:</b>
  <%=h @album.review %>
</p>

<%= link_to 'Edit', :controller => "albums", :action => "edit", :id => @album.id %> |
<%= link_to 'Back', :controller => "albums", :action => "index" %>

You should be able to click show on the index view, and back on the show view.
The destroy\delete functionality will be fixed later on.

To fix the editing function we must alter the edit.html.erb and the controller. Make the edit view look like this:

<h1>Editing album</h1>

<%= error_messages_for :album %>

<% form_for :album, @album, :url => { :controller => "albums", :action => "update" } do |f| %>
  <p>
    <b>Title</b><br />
    <%= f.text_field :title %>
  </p>

  <p>
    <b>Review</b><br />
    <%= f.text_area :review %>
  </p>

  <p>
    <%= f.submit "Update" %>
  </p>
<% end %>

<%= link_to 'Show', :controller => "albums", :action => "show", :id => @album.id %> |
<%= link_to 'Back', :controller => "albums", :action => "index" %>

For help on form_for I recommend the Rails documentation.

Then edit the controllers update method:

class AlbumsController < ApplicationController
  # GET /albums
  # GET /albums.xml
  def index
    @albums = Album.find(:all)

    respond_to do |format|
      format.html # index.html.erb
      format.xml  { render :xml => @albums }
    end
  end

  # GET /albums/1
  # GET /albums/1.xml
  def show
    @album = Album.find(params[:id])

    respond_to do |format|
      format.html # show.html.erb
      format.xml  { render :xml => @album }
    end
  end

  # GET /albums/new
  # GET /albums/new.xml
  def new
    @album = Album.new

    respond_to do |format|
      format.html # new.html.erb
      format.xml  { render :xml => @album }
    end
  end

  # GET /albums/1/edit
  def edit
    @album = Album.find(params[:id])
  end

  # POST /albums
  # POST /albums.xml
  def create
    @album = Album.new(params[:album])

    respond_to do |format|
      if @album.save
        flash[:notice] = 'Album was successfully created.'
        format.html { redirect_to(@album) }
        format.xml  { render :xml => @album, :status => :created, :location => @album }
      else
        format.html { render :action => "new" }
        format.xml  { render :xml => @album.errors, :status => :unprocessable_entity }
      end
    end
  end

  # PUT /albums/1
  # PUT /albums/1.xml
  def update
     @album = Album.find(params[:id]) 

     respond_to do |format|
       if @album.update_attributes(params[:album])
         flash[:notice] = 'Album was successfully updated.'
         format.html { redirect_to(:controller => "albums", :action => "show", :id => @album.id) }
         format.xml  { head :ok }
       else
         format.html { render :action => "edit" }
         format.xml  { render :xml => @album.errors, :status => :unprocessable_entity }
       end
     end
   end  

  # DELETE /albums/1
  # DELETE /albums/1.xml
  def destroy
    @album = Album.find(params[:id])
    @album.destroy

    respond_to do |format|
      format.html { redirect_to(albums_url) }
      format.xml  { head :ok }
    end
  end
end

Now let’s fix the new functionality. As you might have guessed, this also takes two steps. The new new.html.erb:

<h1>New album</h1>

<%= error_messages_for :album %>

<% form_for :album, @album, :url => { :controller => "albums", :action => "create" } do |f| %>
  <p>
    <b>Title</b><br />
    <%= f.text_field :title %>
  </p>

  <p>
    <b>Review</b><br />
    <%= f.text_area :review %>
  </p>

  <p>
    <%= f.submit "Create" %>
  </p>
<% end %>

<%= link_to 'Back', :controller => "albums", :action => "index" %>

And update the Albums controller create method:

class AlbumsController < ApplicationController
  # GET /albums
  # GET /albums.xml
  def index
    @albums = Album.find(:all)

    respond_to do |format|
      format.html # index.html.erb
      format.xml  { render :xml => @albums }
    end
  end

  # GET /albums/1
  # GET /albums/1.xml
  def show
    @album = Album.find(params[:id])

    respond_to do |format|
      format.html # show.html.erb
      format.xml  { render :xml => @album }
    end
  end

  # GET /albums/new
  # GET /albums/new.xml
  def new
    @album = Album.new

    respond_to do |format|
      format.html # new.html.erb
      format.xml  { render :xml => @album }
    end
  end

  # GET /albums/1/edit
  def edit
    @album = Album.find(params[:id])
  end

  # POST /albums
  # POST /albums.xml
  def create
     @album = Album.new(params[:album]) 

     respond_to do |format|
       if @album.save
         flash[:notice] = 'Album was successfully created.'
         format.html { redirect_to(:controller => "albums", :action => "show", :id => @album.id) }
         format.xml  { render :xml => @album, :status => :created, :location => @album }
       else
         format.html { render :action => "new" }
         format.xml  { render :xml => @album.errors, :status => :unprocessable_entity }
       end
     end
  end  

  # PUT /albums/1
  # PUT /albums/1.xml
  def update
     @album = Album.find(params[:id]) 

     respond_to do |format|
       if @album.update_attributes(params[:album])
         flash[:notice] = 'Album was successfully updated.'
         format.html { redirect_to(:controller => "albums", :action => "show", :id => @album.id) }
         format.xml  { head :ok }
       else
         format.html { render :action => "edit" }
         format.xml  { render :xml => @album.errors, :status => :unprocessable_entity }
       end
     end
   end  

  # DELETE /albums/1
  # DELETE /albums/1.xml
  def destroy
    @album = Album.find(params[:id])
    @album.destroy

    respond_to do |format|
      format.html { redirect_to(albums_url) }
      format.xml  { head :ok }
    end
  end
end

Finally update the destroy action in the the albums controller to look like this:

class AlbumsController < ApplicationController
  # GET /albums
  # GET /albums.xml
  def index
    @albums = Album.find(:all)

    respond_to do |format|
      format.html # index.html.erb
      format.xml  { render :xml => @albums }
    end
  end

  # GET /albums/1
  # GET /albums/1.xml
  def show
    @album = Album.find(params[:id])

    respond_to do |format|
      format.html # show.html.erb
      format.xml  { render :xml => @album }
    end
  end

  # GET /albums/new
  # GET /albums/new.xml
  def new
    @album = Album.new

    respond_to do |format|
      format.html # new.html.erb
      format.xml  { render :xml => @album }
    end
  end

  # GET /albums/1/edit
  def edit
    @album = Album.find(params[:id])
  end

  # POST /albums
  # POST /albums.xml
  def create
     @album = Album.new(params[:album]) 

     respond_to do |format|
       if @album.save
         flash[:notice] = 'Album was successfully created.'
         format.html { redirect_to(:controller => "albums", :action => "show", :id => @album.id) }
         format.xml  { render :xml => @album, :status => :created, :location => @album }
       else
         format.html { render :action => "new" }
         format.xml  { render :xml => @album.errors, :status => :unprocessable_entity }
       end
     end
  end  

  # PUT /albums/1
  # PUT /albums/1.xml
  def update
     @album = Album.find(params[:id]) 

     respond_to do |format|
       if @album.update_attributes(params[:album])
         flash[:notice] = 'Album was successfully updated.'
         format.html { redirect_to(:controller => "albums", :action => "show", :id => @album.id) }
         format.xml  { head :ok }
       else
         format.html { render :action => "edit" }
         format.xml  { render :xml => @album.errors, :status => :unprocessable_entity }
       end
     end
   end  

  # DELETE /albums/1
  # DELETE /albums/1.xml
  def destroy
    @album = Album.find(params[:id])
    @album.destroy

    respond_to do |format|
      format.html { redirect_to(:controller => "albums", :action => "index&quot  }
      format.xml  { head :ok }
    end
  end
end

Congratulations! The site is back up and running, and you still managed to provide two-nines of uptime

A special thanks to Bill Thayer for notifying me of problems in this post. These issues have all been resolved. Please let me know if you encountered any problems…

The End of Part 2

That wraps things up for part 2. Amongst other topics, part 3 will cover the default route, receptors, named routes and finally RESTful routing. Once again these posts are on a demand bases. If this helped you and you would like another post, let me know. Feel free to let me know if there is something specific you would like me to cover.

Thanks…

Part 3

---

Possibly related posts: (automatically generated)

• Beginners Tutorial: Routing in Rails 2.0 (with REST) - Part 4 of n
• Beginners Tutorial: Routing in Rails 2.0 (with REST) - Part 1 of n
• RoR FrontController
• rails basics