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


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


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


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


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


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>

Options Hash (attrs):

  • :legend (Object)

    Adds a legend tag within the fieldset



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)



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


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>


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>


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


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>


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


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


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"}] %>


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


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


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


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


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