Module: ActionView::Helpers::FormHelper

Defined in:
lib/action_view/helpers/form_helper.rb

Overview

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:

<%= textfield "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

Instance Method Summary collapse

Instance Method Details

#check_box(object, method, options = {}, checked_value = "1", unchecked_value = "0") ⇒ Object

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



123
124
125
 
# File 'lib/action_view/helpers/form_helper.rb', line 123

def check_box(object, method, options = {}, checked_value = "1", unchecked_value = "0")
  InstanceTag.new(object, method, self).to_check_box_tag(options, checked_value, unchecked_value)
end

#file_field(object, method, options = {}) ⇒ Object

Works just like text_field, but returns a input tag of the “file” type instead, which won’t have any default value.



90
91
92
 
# File 'lib/action_view/helpers/form_helper.rb', line 90

def file_field(object, method, options = {})
  InstanceTag.new(object, method, self).to_input_field_tag("file", options)
end

#hidden_field(object, method, options = {}) ⇒ Object

Works just like text_field, but returns a input tag of the “hidden” type instead.



85
86
87
 
# File 'lib/action_view/helpers/form_helper.rb', line 85

def hidden_field(object, method, options = {})
  InstanceTag.new(object, method, self).to_input_field_tag("hidden", options)
end

#password_field(object, method, options = {}) ⇒ Object

Works just like text_field, but returns a input tag of the “password” type instead.



80
81
82
 
# File 'lib/action_view/helpers/form_helper.rb', line 80

def password_field(object, method, options = {})
  InstanceTag.new(object, method, self).to_input_field_tag("password", options)
end

#radio_button(object, method, tag_value, options = {}) ⇒ Object

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



137
138
139
 
# File 'lib/action_view/helpers/form_helper.rb', line 137

def radio_button(object, method, tag_value, options = {})
  InstanceTag.new(object, method, self).to_radio_button_tag(tag_value, options)
end

#text_area(object, method, options = {}) ⇒ Object

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>



103
104
105
 
# File 'lib/action_view/helpers/form_helper.rb', line 103

def text_area(object, method, options = {})
  InstanceTag.new(object, method, self).to_text_area_tag(options)
end

#text_field(object, method, options = {}) ⇒ Object

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



75
76
77
 
# File 'lib/action_view/helpers/form_helper.rb', line 75

def text_field(object, method, options = {})
  InstanceTag.new(object, method, self).to_input_field_tag("text", options)
end