Module: Merb::Helpers::Form

Included in:
GlobalHelpers
Defined in:
merb-helpers/lib/merb-helpers/form/helpers.rb

Overview

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

Defined Under Namespace

Modules: Builder

Instance Method Summary (collapse)

Instance Method Details

- (Object) _new_form_context(name, builder) 



19
20
21
22
23
24
25
26
27
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 19

def _new_form_context(name, builder)
  if name.is_a?(String) || name.is_a?(Symbol)
    ivar = instance_variable_get("@#{name}")
  else
    ivar, name = name, name.class.to_s.snake_case.split('::').last
  end
  builder ||= current_form_context.class if current_form_context
  (builder || self._default_builder).new(ivar, name, self)
end

- (Object) _singleton_form_context 



5
6
7
8
9
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 5

def _singleton_form_context
  self._default_builder = Merb::Helpers::Form::Builder::ResourcefulFormWithErrors unless self._default_builder
  @_singleton_form_context ||=
    self._default_builder.new(nil, nil, self)
end

- (String) button(contents, attrs = {})

Note:

Buttons do not always work as planned in IE: read more...

Note:

Not all mobile browsers support buttons: read more...

Generates a HTML button.

Examples:

<%= button "Initiate Launch Sequence" %>

Parameters:

  • contents (String) —

    Contents of the text area

  • attrs (Hash) (defaults to: {}) —

    HTML attributes

Returns:



344
345
346
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 344

def button(contents, attrs = {})
  current_form_context.button(contents, attrs)
end

- (String) check_box

TODO:

Docs: proper example

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

Examples:

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

Parameters:

  • method (Symbol) —

    Resource attribute

  • attrs (Hash) —

    HTML attributes and options

Returns:



172
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 172

def check_box; end

- (Object) current_form_context 



15
16
17
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 15

def current_form_context
  form_contexts.last || _singleton_form_context
end

- (String) 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.

Examples:

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

Parameters:

  • object_or_url (Object, String) —

    Object to delete or URL to send the request to.

  • contents (String) (defaults to: "Delete") —

    HTML contained within the button tag.

  • attrs (Hash) (defaults to: {}) —

    HTML attributes.

Returns:



364
365
366
367
368
369
370
371
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 364

def delete_button(object_or_url, contents="Delete", attrs = {})
  url = object_or_url.is_a?(String) ? object_or_url : resource(object_or_url)
  button_text = (contents || 'Delete')
  tag :form, :class => 'delete-btn', :action => url, :method => :post do
    tag(:input, :type => :hidden, :name => "_method", :value => "DELETE") <<
    tag(:input, attrs.merge(:value => button_text, :type => :submit))
  end
end

- (String) error_messages_for(obj = nil, opts = {}) Also known as: error_messages

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

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' %>

Parameters:

  • obj (Object) (defaults to: nil) —

    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:



402
403
404
405
406
407
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 402

def error_messages_for(obj = nil, opts = {})
  current_form_context.error_messages_for(obj, opts[:error_class] || "error", 
    opts[:build_li] || "<li>%s</li>", 
    opts[:header] || "<h2>Form submission failed because of %s problem%s</h2>",
    opts.key?(:before) ? opts[:before] : true)
end

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

Creates a scope around a specific resource object like form_for, but does not 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 =%>

Parameters:

  • name (Model, Resource) —

    Model or Resource

  • attrs (Hash) (defaults to: {}) —

    HTML attributes



109
110
111
112
113
114
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 109

def fields_for(name, attrs = {}, &blk)
  attrs ||= {}
  with_form_context(name, attrs.delete(:builder)) do
    capture(&blk)
  end
end

- (String) fieldset(attrs = {}, &blk)

Note:

Block helpers use the <%= =%> syntax

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

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

Generates the HTML:

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

Parameters:

  • attrs (Hash) (defaults to: {}) —

    HTML attributes and options

Options Hash (attrs):

  • :legend (Object) —

    Adds a legend tag within the fieldset

Returns:



136
137
138
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 136

def fieldset(attrs = {}, &blk)
  _singleton_form_context.fieldset(attrs, &blk)
end

- (Object) fieldset_for(name, attrs = {}, &blk)

See Also:



142
143
144
145
146
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 142

def fieldset_for(name, attrs = {}, &blk)
  with_form_context(name, attrs.delete(:builder)) do
    current_form_context.fieldset(attrs, &blk)
  end
end

- (String) file_field

Provides a HTML file input.

Examples:

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

Used with a model:

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

Parameters:

  • name (Symbol) —

    Model or Resource

  • attrs (Hash) —

    HTML attributes

Returns:



186
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 186

def file_field; end

- (String) form(*args, &blk)

Note:

Block helpers use the <%= =%> syntax

Note:

A multipart enctype is automatically set if the form contains a file upload field

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

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

Parameters:

  • attrs (Hash) —

    HTML attributes

Returns:



59
60
61
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 59

def form(*args, &blk)
  _singleton_form_context.form(*args, &blk)
end

- (Object) form_contexts 



11
12
13
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 11

def form_contexts
  @_form_contexts ||= []
end

- (String) form_for(name, attrs = {}, &blk)

Note:

Block helpers use the <%= =%> syntax

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

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

Parameters:

  • name (Model, Resource) —

    Model or Resource

  • attrs (Hash) (defaults to: {}) —

    HTML attributes

Returns:



88
89
90
91
92
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 88

def form_for(name, attrs = {}, &blk)
  with_form_context(name, attrs.delete(:builder)) do
    current_form_context.form(attrs, &blk)
  end
end

- (String) hidden_field

Provides a HTML hidden input field.

Examples:

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

Parameters:

  • name (Symbol) —

    Model or Resource

  • attrs (Hash) —

    HTML attributes

Returns:



200
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 200

def hidden_field; end

- (String) label(*args)

Provides a generic HTML label.

Examples:

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

Parameters:

  • attrs (Hash) —

    HTML attributes

Returns:



211
212
213
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 211

def label(*args)
  current_form_context.label(*args)
end

- (String) password_field

Provides a HTML password input.

Examples:

<%= 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' %>

Parameters:

  • name (Symbol) —

    Model or Resource

  • attrs (Hash) —

    HTML attributes

Returns:



227
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 227

def password_field; end

- (String) radio_button

Provides a HTML radio input tag.

Examples:

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

Parameters:

  • method (Symbol) —

    Resource attribute

  • attrs (Hash) —

    HTML attributes and options

Returns:



244
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 244

def radio_button; end

- (String) radio_group

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

Examples:

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

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

Parameters:

  • method (Symbol) —

    Resource attribute

  • arr (Array) —

    Choices

Returns:



260
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 260

def radio_group; end

- (String) select

Provides a HTML select.

Examples:

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

Parameters:

  • method (Symbol) —

    Resource attribute

  • attrs (Hash) —

    HTML attributes and options

Returns:



285
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 285

def select; end

- (String) submit(contents, attrs = {})

Generates a HTML submit button.

Examples:

<%= submit "Process" %>

Parameters:

  • value (String) —

    Sets the value attribute.

  • attrs (Hash) (defaults to: {}) —

    HTML attributes.

Returns:



382
383
384
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 382

def submit(contents, attrs = {})
  current_form_context.submit(contents, attrs)
end

- (String) text_area

Provides a HTML textarea tag.

Examples:

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

Used with a model:

<%= text_area :comments %>

Parameters:

  • contents (String) —

    Contents of the text area

  • attrs (Hash) —

    HTML attributes

Returns:



299
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 299

def text_area; end

- (String) text_field

Provides a HTML text input tag.

Examples:

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

Parameters:

  • name (Model, Resource) —

    Model or Resource

  • attrs (Hash) —

    HTML attributes

Returns:



315
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 315

def text_field; end

- (Object) with_form_context(name, builder) 



29
30
31
32
33
34
 
# File 'merb-helpers/lib/merb-helpers/form/helpers.rb', line 29

def with_form_context(name, builder)
  form_contexts.push(_new_form_context(name, builder))
  ret = yield
  form_contexts.pop
  ret
end