Ruby-on-Rails

Web Forms and Ruby on Rails

15.16 Generating Forms for Manipulating Model Objects

Problem

You want to define actions that let a user create or edit objects stored in the database.

Solution

Let_s create a simple model, and then build forms for it. Here_s some MySQL code to create a table of key-value pairs: 

  use mywebapp_development;
  DROP TABLE IF EXISTS items;
  CREATE TABLE `items` (
    `id` int(11) NOT NULL auto_increment,
    `name` varchar(255) NOT NULL default __,
    `value` varchar(40) NOT NULL default _[empty]_,
    PRIMARY KEY (`id`)
  );

Now, from the command line, create the model class, along with a controller and views:

  $ ./script/generate model Item
        exists  app/models/
        exists  test/unit/
        exists  test/fixtures/
        create  app/models/item.rb
        create  test/unit/item_test.rb
        create  test/fixtures/items.yml
        create  db/migrate
        create  db/migrate/ 001_create_items.rb

  $ ./script/generate controller items new create edit
        exists  app/controllers/
        exists  app/helpers/
        create  app/views/items
        exists  test/functional/
        create  app/controllers/ items_controller.rb
        create  test/functional/ items_controller_test.rb
        create  app/helpers/items_helper.rb
        create  app/views/items/new.rhtml
        create  app/views/items/edit.rhtml

The first step is to customize a view. Let_s start with app/views/items/new.rhtml. Edit it to look like this:

  <!-- app/views/items/new.rhtml -->

  <%= form_tag :action => "create" %>
   Name: <%= text_field "item", "name"
%><br />
   Value: <%= text_field "item", "value"
%><br />
   <%= submit_tag %>
  <%= end_form_tag %>

All these method calls generate HTML: form_tag opens a <FORM> tag, submit_tag generates a submit button, and so on. You can type out the same HTML by hand and Rails won_t care, but it_s easier to make method calls, and it makes your templates neater.

The text_field call is a little more involved. It creates an <INPUT> tag that shows up in the HTML form as a text entry field. But it also binds the value of that field to one of the members of the @item instance variable. This code creates a text entry field that_s bound to the name member of @item:

  <%= text_field "item", "name" %>

But what_s the @item instance variable? Well, it_s not defined yet, because we_re still using the generated controller. If you try to access the page /items/new page right now, you may get an error complaining about an unexpected nil value. The nil value is the @item variable, which gets used (in text_field calls) without ever being defined.

Let_s customize the ItemsController class so that the new action sets the @item instance variable properly. We_ll also implement the create action so that something actually happens when the user hits the submit button on our generated form.

  class ItemsController < ApplicationController
    def new
      @item = Item.new
    end

    def create
      @item = Item.create(params[:item])
      redirect_to :action => _edit_, :id => @item.id
    end
  end

Now if you access the /items/new page, you_ll see what you_d expect: a form with two text entry fields. The "Name" field will be blank, and the "Value" field will contain the default database value of "[empty]".

Fill out the form and submit, and a new row will be created in the items table. You_ll be redirected to the edit action, which doesn_t exist yet. Let_s create it now. Here_s the controller part (note the similarity between ItemsController#edit and ItemsController#create above):

  class ItemsController < ApplicationController
    def edit
      @item = Item.find(params[:id])

      if request.post?
        @item.update_attributes(params[:item])
        redirect_to :action => _edit_, :id => @item.id
      end
    end
  end

In fact, the edit action is so similar to the create action that its form can be almost identical. The only differences are in the arguments to form_tag:

  <!-- app/views/items/edit.rhtml -->

  <%= form_tag :action => "edit", :id => @item.id %>
   Name: <%= text_field "item", "name"
%><br />
   Value: <%= text_field "item", "value"
%><br />
   <%= submit_tag %>
  <%= end_form_tag %>

Discussion

This is probably the most common day-to-day task faced by web developers. It_s so common that Rails comes with a tool called scaffold that generates this kind of code for you. If you_d invoked generate this way instead of with the arguments given above, Rails would have generate code for the actions given in the Solution, plus a few more:

  $ ./script/generate scaffold Items

Starting off with scaffolding doesn_t mean you can get away with not knowing how Rails form generation works, because you_ll definitely want to customize the scaffolding code.

There are two places in our code where magic happens. The first is the text_field call in the view, which is explained in the Solution. It binds a member of an object (@item.name , for instance) to an HTML form control. If you view the source of the /items/new page, you will see that the form fields look something like this:

  Name: <input type="text" name="item[name]" value="" /><br />
  Value <input type="text" name="item[value]" value="[empty]" /><br />

These special field names are used by the second piece of magic, located in the calls to Item.create (in new) and Item#update_attributes. In both cases, an Item object is fed a hash of new values for its members. This hash is embedded into the params hash, which contains CGI form values.

The names of the HTML form fields (item[name] and item[value]) translate into a params hash that looks like this:

  {
    :item => {
      :name => "Name of the item",
      :value => "Value of the item"
    },
    :controller => "items",
    :action => "create"
  }

So this line of code:

  Item.create(params[:item])

is effectively the same as this line:

  Item.create(:name => "Name of the item", :value => "Value of the item")

The call to Item#update_attributes in the edit action works exactly the same way.

As mentioned above, the views for edit and new are very similar, differing only in the destination of the form. With some minor refactoring, we can remove one of the view files completely.

A call to <%= form_tag %> without any parameters at all sets the form destination to the current URL. Let_s change the new.rhtml file appropriately:

  <!-- app/views/items/new.rhtml -->
  <%= form_tag %>

  Name: <%= text_field "item", "name"
%>&#x00A;
  Value: <%= text_field "item", "value"
%>&#x00A;

  <%= submit_tag %>
  <%= end_form_tag %>

Now the new.rhtml view is suitable for use by both new and edit. We just need to change the new action to call the create method (since the form doesn_t go there anymore), and change the edit action to render new.rhtml instead of edit.rhtml (which can be removed):

  class ItemsController < ApplicationController
     def new
        @item = Item.new
         create if request.post? 
     end

     def edit
         @item = Item.find(params[:id])

          if request.post?
             @item.update_attributes(params[:item])
             redirect_to :action => _edit_, :id => @item.id and return
           end
           render :action => _new_
      end
  end

Remember from Recipe 15.5 that a render call only specifies the template file to be used. The render call in edit won_t actually call the new method, so we don_t need to worry about the new method overwriting our value of @item.

In real life, there would be enough differences in the content surrounding the add and edit forms to a separate view for each action. However, there_s usually enough similarity between the forms themselves that they can be refactored into a single partial view (see Recipe 15.14) which both views share. This is a great example of the DRY (Don_t Repeat Yourself) principle. If there is a single form for both the add and edit views, it_s easier and less error-prone to maintain that form as the database schema changes.