Recipe 15.16. Generating Forms for Manipulating Model Objects

Recipe 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. See Also Recipe 15.5, "Displaying Templates with Render" Recipe 15.14, "Refactoring the View into Partial Snippets of Views"