Ruby on Rails/ActionView/Forms

Basic
Forms are an important part of every web site. We use them to contact the site owners to provide log in credentials or to submit data. Rails has vast support for forms and many build in tags to help you create forms quick and easily.

The most basic form you can get is a simple input field for your name:

This will create a very basic form like

This was achieved by creating a simple action called test.html.erb inside our products view,

An empty action inside the controller was added. The page was called inside the browser http://localhost:3000/products/test/1. Because we haven't altered the routes we have to provide an id of a product. Additionaly Rails has created a "authenticity_token" to provide security features to our form. You also notice that there is an id for our input. Rails provides the id for every form element with the names you provided. Of course this can be altered by providing the proper option.

The following list should give you an overview of some form tags. As most of the tags work in a similar manner, it should be easy to figure out how much of them works. Also be sure to take a look at the official API.

Radio Boxes:

To create radioboxes simply use The above will create If you want to change the id you can pass your own id to to tag (:id => "someid"). To preselect an item the 3 option that the helper receives is supposed to be a boolean.

Submit Button:

will create a submit button

Text fields:

will create an empty text field:

As usual you can add HTML options or specific values

notice that we use "nil" here. This is because we want to create a text field with no pre-defined value:

If we would have provided a name, Rails would add the HTML attribute "value":

Select boxes:

A common task inside forms is to let the user select something from select boxes - or drop downs. To display a simple select box we can combine some handy methods: would create Another nice helper of the select_* family is select_year. When you want the user to choose his year of birth, you may use something like:

This will create a select box with all years, starting from 2009 going to 1900 with the current year (Date.today as the first argument) being pre-selected. Be sure to check out the other helpers for dates Datehelpers

Handling Errors
Now that you know how to display forms correctly in Rails, we are looking for a way to give the user some feedback over his input. Either if it is correct or if he needs to re-enter some values. You have already read about how to validate form data before it gets written into the database. Now you will see how to display the errors. Basically there are two methods that allow us to display errors: error_messages and <tt>error_messages_for</tt>. The name gives a pretty good idea of the difference between these two: <tt>error_messages</tt> displays all errors for the form, while <tt>error_messages_for</tt> displays the errors for a given model.

Using the methods is easy:

will display all the error messages: either default ones or the ones you have specified inside your model (<tt>:message => "Only integers allowed"</tt>). <tt>error_messages_for</tt> is used in a similar manner. Then it display the error message for the field that matches the given name (<tt>:name</tt> in this case)

You can also customize the error messages that are displayed in a box, even more:

Advanced Forms
Until now we mainly worked with form elements that have a <tt>_tag</tt> at the end of the name. When working with a model (e.g. you want to update your data or create a new data set) you want to use the form elements that are more suited for the job. There are no new elements to learn we just use the one we already know but do not add the _tag at the end (compare <tt>form_tag</tt> and <tt>form_for</tt>).

Let's asume we want to create a new Product via a form:

We have a controller that has an action... <tt>products_controller.rb</tt>

... and a view (<tt>view/products/new.html.erb</tt>) that works with our <tt>@product</tt> instance:

will create HTML similar to:

Let's inspect the code: <tt>form_for</tt> has some code on his side, <tt>:product</tt> references the name of the model that we want to use and <tt>@product</tt> is the instance of the object itself (in this case, it's going to be a new product). We loop or "yield" through the <tt>form_for</tt> object with the variable f. The rest uses code you are already familiar with. We use the action "create" to handle the creation of the file.

Restful Resources
The methods shown above may not be exactly what you will see in other Rails applications. Most of them will use RESTful resources. This gives Rails the option to decide what to do with the data. This makes the <tt>form_for</tt> method a lot easier and more readably:

turns into

That is a lot better, isn't it? Now the <tt>form_for</tt> tag looks the same, no matter if you are creating a new product or if you update an existing one. Rails is smart enough to recognize the action and provides us with the correct HTML attributes (see <tt><form action="/products" class="new_product" id="new_product" method="post"></tt>)

To learn more about routing and REST be sure to take a look at Routing.

Using select boxes with a model
We already learnt how to create select boxes with built in helpers. But you may also want to display the contents of a model inside a select box. To show how this is done, we want to select categories from the database, so the user can select the according one:

If you have some categories inside your database the HTML may look similar to

Notice the <tt>.downcase</tt>: this will write the HTML values lowercase, if your database needs to work with it that way. This is just a starting point for your work. To see more examples and explanations, a good start is the official API