ActionView::Helpers::FormHelper

Form helpers are designed to make working with models much easier compared to using just standard HTML elements by providing a set of methods for creating forms based on your models. This helper generates the HTML for forms, providing a method for each sort of input (e.g., text, password, select, and so on). When the form is submitted (i.e., when the user hits the submit button or form.submit is called via JavaScript), the form inputs will be bundled into the params object and passed back to the controller.

There are two types of form helpers: those that specifically work with model attributes and those that don't. This helper deals with those that work with model attributes; to see an example of form helpers that don't work with model attributes, check the ActionView::Helpers::FormTagHelper documentation.

The core method of this helper, form_for, gives you the ability to create a form for a model instance; for example, let's say that you have a model Person and want to create a new instance of it:

    # Note: a @person variable will have been created in the controller.
    # For example: @person = Person.new
    <% form_for :person, @person, :url => { :action => "create" } do |f| %>
      <%= f.text_field :first_name %>
      <%= f.text_field :last_name %>
      <%= submit_tag 'Create' %>
    <% end %>

The HTML generated for this would be:

    <form action="/persons/create" method="post">
      <input id="person_first_name" name="person[first_name]" size="30" type="text" />
      <input id="person_last_name" name="person[last_name]" size="30" type="text" />
      <input name="commit" type="submit" value="Create" />
    </form>

If you are using a partial for your form fields, you can use this shortcut:

    <% form_for :person, @person, :url => { :action => "create" } do |f| %>
      <%= render :partial => f %>
      <%= submit_tag 'Create' %>
    <% end %>

This example will render the people/_form partial, setting a local variable called form which references the yielded FormBuilder.

The params object created when this form is submitted would look like:

    {"action"=>"create", "controller"=>"persons", "person"=>{"first_name"=>"William", "last_name"=>"Smith"}}

The params hash has a nested person value, which can therefore be accessed with params[:person] in the controller. If were editing/updating an instance (e.g., Person.find(1) rather than Person.new in the controller), the objects attribute values are filled into the form (e.g., the person_first_name field would have that person's first name in it).

If the object name contains square brackets the id for the object will be inserted. For example:

  <%= text_field "person[]", "name" %>

…will generate the following ERb.

  <input type="text" id="person_<%= @person.id %>_name" name="person[<%= @person.id %>][name]" value="<%= @person.name %>" />

If the helper is being used to generate a repetitive sequence of similar form elements, for example in a partial used by render_collection_of_partials, the index option may come in handy. Example:

  <%= text_field "person", "name", "index" => 1 %>

…becomes...

  <input type="text" id="person_1_name" name="person[1][name]" value="<%= @person.name %>" />

An index option may also be passed to form_for and fields_for. This automatically applies the index to all the nested fields.

There are also methods for helping to build form tags in ActionView::Helpers::FormOptionsHelper ActionView::Helpers::DateHelper and ActionView::Helpers::ActiveRecordHelper