Module: Merb::Helpers::Form

Module | Merb::Helpers::Form
In: | lib/merb-helpers/form/helpers.rb

Form helpers provide a number of methods to simplify the creation of HTML forms. They can work directly with models (bound) or standalone (unbound).

### Methods

_new_form_context _singleton_form_context button check_box current_form_context delete_button error_messages error_messages_for fields_for fieldset fieldset_for file_field form form_contexts form_for hidden_field label password_field radio_button radio_group select submit text_area text_field with_form_context

### Classes and Modules

Module Merb::Helpers::Form::Builder

### Public Instance methods

_new_form_context(name, builder)
_singleton_form_context()
button(contents, attrs = {})

Generates a HTML button.

#### Parameters

contents<String>: | HTML contained within the button tag
attrs<Hash>: | HTML attributes

#### Returns

String: | HTML

#### Notes

     * Buttons do not always work as planned in IE
       http://www.peterbe.com/plog/button-tag-in-IE
     * Not all mobile browsers support buttons
       http://nickcowie.com/2007/time-to-stop-using-the-button-element/

#### Example

      <%= button "Initiate Launch Sequence" %>

check_box()

Provides a generic HTML checkbox input tag. There are two ways this tag can be generated, based on the option :boolean. If not set to true, a "magic" input is generated. Otherwise, an input is created that can be easily used for passing an array of values to the application.

#### Parameters

method<Symbol>: | Resource attribute
attrs<Hash>: | HTML attributes and options

#### Returns

String: | HTML

#### Example

      <%= check_box :name => "is_activated", :value => "1" %>
      <%= check_box :name => "choices[]", :boolean => false, :value => "dog" %>
      <%= check_box :name => "choices[]", :boolean => false, :value => "cat" %>
      <%= check_box :name => "choices[]", :boolean => false, :value => "weasle" %>

Used with a model:

      <%= check_box :is_activated, :label => "Activated?" %>

current_form_context()
delete_button(object_or_url, contents="Delete", attrs = {})

Generates a HTML delete button.

If an object is passed as first parameter, Merb will try to use the resource url for the object If the object doesn‘t have a resource view, pass a url

#### Parameters

object_or_url<Object> or <String>: | Object to delete or URL to send the request to
contents<String>: | HTML contained within the button tag
attrs<Hash>: | HTML attributes

#### Returns

String: | HTML

#### Example

      <%= delete_button @article, "Delete article now", :class => 'delete-btn' %>
      <%= delete_button url(:article, @article)%>

error_messages(obj = nil, opts = {})

Alias for error_messages_for

error_messages_for(obj = nil, opts = {})

Provides a HTML formatted display of resource errors in an unordered list with a h2 form submission error

#### Parameters

obj<Object>: | Model or Resource
error_class<String>: | CSS class to use for error container
build_li<String>: | Custom li tag to wrap each error in
header<String>: | Custom header text for the error container
before<Boolean>: | Display the errors before or inside of the form

#### Returns

String: | HTML

#### Examples

      <%= error_messages_for @person %>
      <%= error_messages_for @person {|errors| "You can has probs nao: #{errors.size} of em!"}
      <%= error_messages_for @person, lambda{|error| "<li class='aieeee'>#{error.join(' ')}"} %>
      <%= error_messages_for @person, nil, 'bad_mojo' %>

fields_for(name, attrs = {}, &blk)

Creates a scope around a specific resource object like form_for, but doesnt create the form tags themselves. This makes fields_for suitable for specifying additional resource objects in the same form.

#### Examples

      <%= form_for @person do %>
        <%= text_field :first_name, :label => "First Name" %>
        <%= text_field :last_name,  :label => "Last Name" %>
        <%= fields_for @permission do %>
          <%= check_box :is_admin, :label => "Administrator" %>
        <% end =%>
        <%= submit "Create" %>
      <% end =%>

fieldset(attrs = {}, &blk)

Provides the ability to create quick fieldsets as blocks for your forms.

#### Parameters

attrs<Hash>: | HTML attributes and options

#### Options

`legend`: | Adds a legend tag within the fieldset

#### Returns

String: | HTML

#### Notes

Block helpers use the <%= =%> syntax

#### Example

      <%= fieldset :legend => "Customer Options" do %>
        ...your form elements
      <% end =%>

Generates the HTML:

      <fieldset>
        <legend>Customer Options</legend>
        ...your form elements
      </fieldset>

fieldset_for(name, attrs = {}, &blk)
file_field()

Provides a HTML file input

#### Parameters

name<Symbol>: | Model or Resource
attrs<Hash>: | HTML attributes

#### Returns

String: | HTML

#### Example

      <%= file_field :name => "file", :label => "File" %>

Used with a model:

      <%= file_field :file, :label => "Choose a file" %>

form(*args, &blk)

Generates a form tag, which accepts a block that is not directly based on resource attributes

#### Parameters

attrs<Hash>: | HTML attributes

#### Returns

String: | HTML

#### Notes

     * Block helpers use the <%= =%> syntax
     * a multipart enctype is automatically set if the form contains a file upload field

#### Example

      <%= form :action => url(:controller => "foo", :action => "bar", :id => 1) do %>
        <%= text_field :name => "first_name", :label => "First Name" %>
        <%= submit "Create" %>
      <% end =%>

      Generates the HTML:

      <form action="/foo/bar/1" method="post">
        <label for="first_name">First Name</label>
        <input type="text" id="first_name" name="first_name" />
        <input type="submit" value="Create" />
      </form>

form_contexts()
form_for(name, attrs = {}, &blk)

Generates a resource specific form tag which accepts a block, this also provides automatic resource routing.

#### Parameters

name<Symbol>: | Model or Resource
attrs<Hash>: | HTML attributes

#### Returns

String: | HTML

#### Notes

     * Block helpers use the <%= =%> syntax

#### Example

      <%= form_for @person do %>
        <%= text_field :first_name, :label => "First Name" %>
        <%= text_field :last_name,  :label => "Last Name" %>
        <%= submit "Create" %>
      <% end =%>

The HTML generated for this would be:

      <form action="/people" method="post">
        <label for="person_first_name">First Name</label>
        <input type="text" id="person_first_name" name="person[first_name]" />
        <label for="person_last_name">Last Name</label>
        <input type="text" id="person_last_name" name="person[last_name]" />
        <input type="submit" value="Create" />
      </form>

hidden_field()

Provides a HTML hidden input field

#### Parameters

name<Symbol>: | Model or Resource
attrs<Hash>: | HTML attributes

#### Returns

String: | HTML

#### Example

      <%= hidden_field :name => "secret", :value => "some secret value" %>

Used with a model:

      <%= hidden_field :identifier %>
      # => <input type="hidden" id="person_identifier" name="person[identifier]" value="#{@person.identifier}" />

label(*args)

Provides a generic HTML label.

#### Parameters

attrs<Hash>: | HTML attributes

#### Returns

String: | HTML

#### Example

      <%= label "Full Name", :for => "name" %>
      => <label for="name">Full Name</label>

password_field()

Provides a HTML password input.

#### Parameters

name<Symbol>: | Model or Resource
attrs<Hash>: | HTML attributes

#### Returns

String: | HTML

#### Example

      <%= password_field :name => :password, :label => "Password" %>
      # => <label for="password">Password</label><input type="password" id="password" name="password" />

Used with a model:

      <%= password_field :password, :label => 'New Password' %>

radio_button()

Provides a HTML radio input tag

#### Parameters

method<Symbol>: | Resource attribute
attrs<Hash>: | HTML attributes and options

#### Returns

String: | HTML

#### Example

      <%= radio_button :name => "radio_options", :value => "1", :label => "One" %>
      <%= radio_button :name => "radio_options", :value => "2", :label => "Two" %>
      <%= radio_button :name => "radio_options", :value => "3", :label => "Three", :checked => true %>

Used with a model:

      <%= form_for @person do %>
        <%= radio_button :first_name %>
      <% end =%>

radio_group()

Provides a radio group based on a resource attribute. This is generally used within a resource block such as `form_for`.

#### Parameters

method<Symbol>: | Resource attribute
arr<Array>: | Choices

#### Returns

String: | HTML

#### Examples

      <%# the labels are the options %>
      <%= radio_group :my_choice, [5,6,7] %>

      <%# custom labels %>
      <%= radio_group :my_choice, [{:value => 5, :label => "five"}] %>

select()

Provides a HTML select

#### Parameters

method<Symbol>: | Resource attribute
attrs<Hash>: | HTML attributes and options

#### Options

`prompt`: | Adds an additional option tag with the provided string with no value.
`selected`: | The value of a selected object, which may be either a string or an array.
`include_blank`: | Adds an additional blank option tag with no value.
`collection`: | The collection for the select options
`text_method`: | Method to determine text of an option (as a symbol). Ex: :text_method => :name will call .name on your record object for what text to display.
`value_method`: | Method to determine value of an option (as a symbol).

#### Returns

String: | HTML

#### Example

      <%= select :name, :collection => %w(one two three) %>

submit(contents, attrs = {})

Generates a HTML submit button.

#### Parameters

value<String>: | Sets the value="" attribute
attrs<Hash>: | HTML attributes

#### Returns

String: | HTML

#### Example

      <%= submit "Process" %>

text_area()

Provides a HTML textarea tag

#### Parameters

contents<String>: | Contents of the text area
attrs<Hash>: | HTML attributes

#### Returns

String: | HTML

#### Example

      <%= text_area "my comments", :name => "comments" %>

Used with a model:

      <%= text_area :comments %>

text_field()

Provides a HTML text input tag

#### Parameters

name<Symbol>: | Model or Resource
attrs<Hash>: | HTML attributes

#### Returns

String: | HTML

#### Example

      <%= text_field :name => :fav_color, :label => "Your Favorite Color" %>
      # => <label for="fav_color">Your Favorite Color</label><input type="text" id="fav_color" name="fav_color" />

Used with a model:

      <%= form_for @person do %>
        <%= text_field :first_name, :label => "First Name" %>
      <% end =%>

with_form_context(name, builder) {|| ...}

[Validate]