Module: ActionView::Helpers::FormHelper

Module | ActionView::Helpers::FormHelper
In: | lib/action_view/helpers/form_helper.rb

Provides a set of methods for working with forms and especially forms related to objects assigned to the template. The following is an example of a complete form for a person object that works for both creates and updates built with all the form helpers. The `@person` object was assigned by an action on the controller:

      <form action="save_person" method="post">
        Name:
        <%= text_field "person", "name", "size" => 20 %>

        Password:
        <%= password_field "person", "password", "maxsize" => 20 %>

        Single?:
        <%= check_box "person", "single" %>

        Description:
        <%= text_area "person", "description", "cols" => 20 %>

        <input type="submit" value="Save">
      </form>

…is compiled to:

      <form action="save_person" method="post">
        Name:
        <input type="text" id="person_name" name="person[name]"
          size="20" value="<%= @person.name %>" />

        Password:
        <input type="password" id="person_password" name="person[password]"
          size="20" maxsize="20" value="<%= @person.password %>" />

        Single?:
        <input type="checkbox" id="person_single" name="person[single]" value="1" />

        Description:
        <textarea cols="20" rows="40" id="person_description" name="person[description]">
          <%= @person.description %>
        </textarea>

        <input type="submit" value="Save">
      </form>

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

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

…becomes:

      <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 %>" />

There‘s also methods for helping to build form tags in classes/ActionView/Helpers/FormOptionsHelper.html, classes/ActionView/Helpers/DateHelper.html, and classes/ActionView/Helpers/ActiveRecordHelper.html

### Methods

check_box fields_for file_field form_for hidden_field password_field radio_button text_area text_field

### Public Instance methods

check_box(object_name, method, options = {}, checked_value = "1", unchecked_value = "0")

Returns a checkbox tag tailored for accessing a specified attribute (identified by `method`) on an object assigned to the template (identified by `object`). It‘s intended that `method` returns an integer and if that integer is above zero, then the checkbox is checked. Additional options on the input tag can be passed as a hash with `options`. The `checked_value` defaults to 1 while the default `unchecked_value` is set to 0 which is convenient for boolean values. Usually unchecked checkboxes don‘t post anything. We work around this problem by adding a hidden value with the same name as the checkbox.

Example (call, result). Imagine that @post.validated? returns 1:

      check_box("post", "validated")
        <input type="checkbox" id="post_validate" name="post[validated]" value="1" checked="checked" />
        <input name="post[validated]" type="hidden" value="0" />

Example (call, result). Imagine that @puppy.gooddog returns no:

      check_box("puppy", "gooddog", {}, "yes", "no")
        <input type="checkbox" id="puppy_gooddog" name="puppy[gooddog]" value="yes" />
        <input name="puppy[gooddog]" type="hidden" value="no" />

fields_for(object_name, *args) {|(options[:builder] || FormBuilder.new(object_name, object, self, options, proc))| ...}

Creates a scope around a specific model object like form_for, but doesn‘t create the form tags themselves. This makes fields_for suitable for specifying additional model objects in the same form. Example:

      <% form_for :person, @person, :url => { :action => "update" } do |person_form| %>
        First name: <%= person_form.text_field :first_name %>
        Last name : <%= person_form.text_field :last_name %>

        <% fields_for :permission, @person.permission do |permission_fields| %>
          Admin?  : <%= permission_fields.check_box :admin %>
        <% end %>
      <% end %>

Note: This also works for the methods in FormOptionHelper and DateHelper that are designed to work with an object as base. Like collection_select and datetime_select.

file_field(object_name, method, options = {})

Works just like text_field, but returns an input tag of the "file" type instead, which won‘t have a default value.

form_for(object_name, *args, &proc)

Creates a form and a scope around a specific model object, which is then used as a base for questioning about values for the fields. Examples:

      <% form_for :person, @person, :url => { :action => "update" } do |f| %>
        First name: <%= f.text_field :first_name %>
        Last name : <%= f.text_field :last_name %>
        Biography : <%= f.text_area :biography %>
        Admin?    : <%= f.check_box :admin %>
      <% end %>

Worth noting is that the form_for tag is called in a ERb evaluation block, not a ERb output block. So that‘s `<% %>`, not `<%= %>`. Also worth noting is that the form_for yields a form_builder object, in this example as f, which emulates the API for the stand-alone FormHelper methods, but without the object name. So instead of `text_field :person, :name`, you get away with `f.text_field :name`.

That in itself is a modest increase in comfort. The big news is that form_for allows us to more easily escape the instance variable convention, so while the stand-alone approach would require `text_field :person, :name, :object => person` to work with local variables instead of instance ones, the form_for calls remain the same. You simply declare once with `:person, person` and all subsequent field calls save `:person` and `:object => person`.

Also note that form_for doesn‘t create an exclusive scope. It‘s still possible to use both the stand-alone FormHelper methods and methods from FormTagHelper. Example:

      <% form_for :person, @person, :url => { :action => "update" } do |f| %>
        First name: <%= f.text_field :first_name %>
        Last name : <%= f.text_field :last_name %>
        Biography : <%= text_area :person, :biography %>
        Admin?    : <%= check_box_tag "person[admin]", @person.company.admin? %>
      <% end %>

Note: This also works for the methods in FormOptionHelper and DateHelper that are designed to work with an object as base. Like collection_select and datetime_select.

Html attributes for the form tag can be given as :html => {…}. Example:

      <% form_for :person, @person, :html => {:id => 'person_form'} do |f| %>
        ...
      <% end %>

You can also build forms using a customized FormBuilder class. Subclass FormBuilder and override or define some more helpers, then use your custom builder like so:

      <% form_for :person, @person, :url => { :action => "update" }, :builder => LabellingFormBuilder do |f| %>
        <%= f.text_field :first_name %>
        <%= f.text_field :last_name %>
        <%= text_area :person, :biography %>
        <%= check_box_tag "person[admin]", @person.company.admin? %>
      <% end %>

In many cases you will want to wrap the above in another helper, such as:

      def labelled_form_for(name, object, options, &proc)
        form_for(name, object, options.merge(:builder => LabellingFormBuiler), &proc)
      end

hidden_field(object_name, method, options = {})

Works just like text_field, but returns an input tag of the "hidden" type instead.

password_field(object_name, method, options = {})

Works just like text_field, but returns an input tag of the "password" type instead.

radio_button(object_name, method, tag_value, options = {})

Returns a radio button tag for accessing a specified attribute (identified by `method`) on an object assigned to the template (identified by `object`). If the current value of `method` is `tag_value` the radio button will be checked. Additional options on the input tag can be passed as a hash with `options`. Example (call, result). Imagine that @post.category returns "rails":

      radio_button("post", "category", "rails")
      radio_button("post", "category", "java")
        <input type="radio" id="post_category" name="post[category]" value="rails" checked="checked" />
        <input type="radio" id="post_category" name="post[category]" value="java" />

text_area(object_name, method, options = {})

Returns a textarea opening and closing tag set tailored for accessing a specified attribute (identified by `method`) on an object assigned to the template (identified by `object`). Additional options on the input tag can be passed as a hash with `options`.

Example (call, result):

      text_area("post", "body", "cols" => 20, "rows" => 40)
        <textarea cols="20" rows="40" id="post_body" name="post[body]">
          #{@post.body}
        </textarea>

text_field(object_name, method, options = {})

Returns an input tag of the "text" type tailored for accessing a specified attribute (identified by `method`) on an object assigned to the template (identified by `object`). Additional options on the input tag can be passed as a hash with `options`.

Examples (call, result):

      text_field("post", "title", "size" => 20)
        <input type="text" id="post_title" name="post[title]" size="20" value="#{@post.title}" />

[Validate]