List Boxes in Rails

Today we will tackle the more thornier controls: list boxes and combo boxes. Let’s add the ability to select the origin and destination airports for our flight from a list of available airports.

Airports

We need a small list of airports to choose from, so let’s create a lookup table.

script/generate scaffold Airport code:string
rake db:migrate

Use the generated scaffold UI at /airports to add a few airports. Here’s what I chose:

We also need add two columns to our flight model:

script/generate migration AddAirportsToFlight origin_id:integer destination_id:integer
rake db:migrate

Notice that we’re storing integers, not strings this time. This is so we can hold foreign keys to the appropriate rows in the Airports table. We also need to open up the flight.rb model file and specify the relationship between flights and airports.

class Flight < ActiveRecord::Base

  belongs_to :origin, :class_name => "Airport" 
  belongs_to :destination, :class_name => "Airport" 

end

If you’re not very familiar with ActiveRecord yet, the code here uses a slightly more advanced syntax of the belongs_to method since the lookup table class name is not related to the attribute names we want in our Flight class. (If Rails knew that “origin_id” and “destination_id” are intended to be foreign keys to the Airports table, that would be magic indeed).

Similarly, let’s hook things up on the Airport side of the equation:

class Airport < ActiveRecord::Base

  has_many :departures, :class_name => "Flight", :foreign_key => "origin_id" 
  has_many :arrivals, :class_name => "Flight", :foreign_key => "destination_id" 

end

Before we use any GUI sugar, open up your console and hook up a flight to two airports (I’ve omitted a bunch of the console output for clarity):

>> f = Flight.find(1)
=> #<Flight id: 1, number: "123", created_at: "2008-04-05 20:05:24", updated_at: "2008-04-05 20:05:24", meal: false, equipment: nil, origin_id: nil, destination_id: nil>

>> ord = Airport.find_by_code 'ORD'
>> pdx = Airport.find_by_code 'PDX'

>> f.origin = ord
>> f.destination = pdx
>> f.save!
=> true

And now, behold the beauty and power of ActiveRecord associations that give us a natural-language vocabulary for our models.

>> ord.departures
=> [#<Flight id: 1, number: "123", created_at: "2008-04-05 20:05:24", updated_at: "2008-04-06 10:22:23", meal: false, equipment: nil, origin_id: 1, destination_id: 2>]
>> pdx.arrivals
=> [#<Flight id: 1, number: "123", created_at: "2008-04-05 20:05:24", updated_at: "2008-04-06 10:22:23", meal: false, equipment: nil, origin_id: 1, destination_id: 2>]

Awesome!

Now let’s see how we can make those associations in our form instead of through the console.

Selecting Airports

In HTML, listboxes and combobox (drop-down list) controls are both known as selection lists, and are implemented by the <select> tag. Nested inside the <select> tag are one or more option tags. Each option describes one list item.

The form_for builder gives us two waysto construct selection lists without having to manually construct each <option> tag individually. One is the select helper, which provides full control over how the <select> and <option> tags are generated. Another is collection_select, which provides a simpler syntax if:

• You can provide the list of items as a Ruby collection
• Each item in the collection has a method that can be called to provide a displayable string for that item
• Each item also has a method that can be called to supply the value that should be sent to the application when the item is selected by the user.

These three conditions are the 80% case when you’re constructing the list from an ActiveRecord table. Some code will make it clearer. Open up new.html.erb again and add this code into the form:

<% airports = Airport.find(:all, :order => :code) %>
<p>Depart from: 
  <%= f.collection_select :origin_id, airports, :id, :code %>
</p>

<p>Arrive at: 
  <%= f.collection_select :destination_id, airports, :id, :code %>
</p>

We start by capturing all of the airports into the airports variable. Note that we use the <% %> syntax, without the equal sign, whenever we don’t want the result to be sent back to the browser.

We then use the collection_select helper to construct our combo box. Here are the parameters we had to pass:

• First is the attribute of our model we’re trying to assign to (origin_id or destination_id)
• Second is the Ruby collection. We will get one <option> tag – one item in the list – for each object in the collection.
• Third is the method on the collection items that should be called on the selected item when it’s time to transmit the selection to the application.
• Last is the method on the collection items that should be called to generate that item’s displayed string in the list.

Navigate to the form in your browser:

Finally, let’s make sure we understand how this ends up in our new flight model. Select some values and click Create.

Back To That Bridge Again

In my case, I created flight #444 from Chicago to Portland on a Boeing 777. Take a look at your log file (log/development.log) and find where the create action was called. Mine looks like this:

Processing FlightsController#create (for 127.0.0.1 at 2008-04-06 14:31:39) [POST]
  Session ID: BAh7BzoMY3NyZl9pZCIlZmRhM2FmODI0ZjA1MjYwMzgxMGJiMjcyYjBiOTNi%0AMTUiCmZsYXNoSUM6J0FjdGlvbkNvbnRyb2xsZXI6OkZsYXNoOjpGbGFzaEhh%0Ac2h7AAY6CkB1c2VkewA%3D--273a533fb4cee21ea44cb1ccdc6d70db908d7525
  Parameters: {"commit"=>"Create", "authenticity_token"=>"e9e1c0b0d744f33db348cd70a69cf70d6126c66b", "action"=>"create", "controller"=>"flights", "flight"=>{"number"=>"444", "origin_id"=>"1", "meal"=>"0", "destination_id"=>"2", "equipment"=>"747"}}
  Flight Create (0.000350)   INSERT INTO flights ("updated_at", "number", "origin_id", "meal", "destination_id", "equipment", "created_at") VALUES('2008-04-06 14:31:39', '444', 1, 'f', 2, '747', '2008-04-06 14:31:39')
Redirected to http://localhost:3000/flights/4
Completed in 0.00958 (104 reqs/sec) | DB: 0.00035 (3%) | 302 Found [http://localhost/flights]

Zooming in on just the parameters and reformatting for clarity:

Parameters: { "commit"=>"Create",
                   "authenticity_token"=>"e9e1c0b0d744f33db348cd70a69cf70d6126c66b",
                   "action"=>"create", 
                   "controller"=>"flights", 
                   "flight"=> { "number"=>"444", 
                                "origin_id"=>"1", 
                                "meal"=>"0", 
                                "destination_id"=>"2", 
                                "equipment"=>"747"}
                              }

See how all of our form data is in the tidy flight hash? We can easily access all the form values with params[:flight]. The important thing to notice are the values that came across for the selected airports.

Here’s another way to confirm to ourselves that it worked. Open up the Rails console again and find the flight:

>> f = Flight.find_by_number '444'
=> #<Flight id: 4, number: "444", created_at: "2008-04-06 14:31:39", updated_at: "2008-04-06 14:31:39", meal: false, equipment: "747", origin_id: 1, destination_id: 2>
>> f.origin.code
=> "ORD"

And for fun, check out the arrivals for the Portland airport:

>> Airport.find_by_code("PDX").arrivals
=> [#<Flight id: 1, number: "123", created_at: "2008-04-05 20:05:24", updated_at: "2008-04-06 10:22:23", meal: false, equipment: nil, origin_id: 1, destination_id: 2>, #<Flight id: 4, number: "444", created_at: "2008-04-06 14:31:39", updated_at: "2008-04-06 14:31:39", meal: false, equipment: "747", origin_id: 1, destination_id: 2>]

List Box instead of Drop-down Box

If you’d prefer to show a listbox instead of a combobox, we need to tell the browser to show more than one item at a time. To do that we need to pass two more parameters to the collection_select method:

• An empty hash. See the Rails API docs for more info here – this hash can contain optional elements like whether to include a blank item at the top of the list, etc.
• A hash of attributes that should be glued into the HTML <select> tag. We need to insert a size attribute with the value 3. Anything larger than 1 will end up looking like a listbox instead of a combobox.

Adding these options and playing with our <p> tags a bit means we have code that now looks like this:

  <p>Depart from:</p> 
    <%= f.collection_select :origin_id, airports, :id, :code, {}, {:size => 3}  %>

  <p>Arrive at:</p>
    <%= f.collection_select :destination_id, airports, :id, :code, {}, {:size => 3} %>
  </p>

and the form now looks like this:

You Are Now Free To Create Your Own Forms

We’ve gotten a few questions regarding the best way to handle several different models on the same form, multiples of the same model on the same form, and how to use advanced options of how to use form_for when your controller is a namespace (if your controller is within an “admin” namespace, for example). We’ll try to address those issues in subsequent postings in the very near future.

But for now, that’s it for our whirlwind tour of forms in Rails. Remember:

• Ruby templates generate HTML. So learn HTML.
• The params has is your bridge between your user and your application. Learn to use the log files well.
• Follow Rails conventions to make life easy.

Questions? Drop us a comment.