module Merb::Helpers::Form
Form helpers provide a number of methods to simplify the creation of HTML forms. They can work directly with models (bound) or standalone (unbound).
Public Instance Methods
# File 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
# File 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
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?" %>
# File lib/merb-helpers/form/helpers.rb, line 175 def check_box; end
# File lib/merb-helpers/form/helpers.rb, line 15 def current_form_context form_contexts.last || _singleton_form_context end
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' %>
# File lib/merb-helpers/form/helpers.rb, line 435 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
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 =%>
# File lib/merb-helpers/form/helpers.rb, line 111 def fields_for(name, attrs = {}, &blk) attrs ||= {} with_form_context(name, attrs.delete(:builder)) do capture(&blk) end end
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>
# File lib/merb-helpers/form/helpers.rb, line 143 def fieldset(attrs = {}, &blk) _singleton_form_context.fieldset(attrs, &blk) end
# File lib/merb-helpers/form/helpers.rb, line 147 def fieldset_for(name, attrs = {}, &blk) with_form_context(name, attrs.delete(:builder)) do current_form_context.fieldset(attrs, &blk) end end
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" %>
# File lib/merb-helpers/form/helpers.rb, line 192 def file_field; end
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>
# File lib/merb-helpers/form/helpers.rb, line 61 def form(*args, &blk) _singleton_form_context.form(*args, &blk) end
# File lib/merb-helpers/form/helpers.rb, line 11 def form_contexts @_form_contexts ||= [] end
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>
# File lib/merb-helpers/form/helpers.rb, line 93 def form_for(name, attrs = {}, &blk) with_form_context(name, attrs.delete(:builder)) do current_form_context.form(attrs, &blk) end end
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' %>
# File lib/merb-helpers/form/helpers.rb, line 243 def password_field; end
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"}] %>
# File lib/merb-helpers/form/helpers.rb, line 282 def radio_group; end
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) %>
# File lib/merb-helpers/form/helpers.rb, line 303 def select; end
Generates a HTML submit button.
Parameters¶ ↑
- value<String>
-
Sets the value=“” attribute
- attrs<Hash>
-
HTML attributes
Returns¶ ↑
- String
-
HTML
Example¶ ↑
<%= submit "Process" %>
# File lib/merb-helpers/form/helpers.rb, line 414 def submit(contents, attrs = {}) current_form_context.submit(contents, attrs) end
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 %>
# File lib/merb-helpers/form/helpers.rb, line 320 def text_area; end
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 =%>
# File lib/merb-helpers/form/helpers.rb, line 340 def text_field; end
# File 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
Private Instance Methods
# File lib/merb-helpers/form/helpers.rb, line 445 def bound?(*args) args.first.is_a?(Symbol) end