| Module | Merb::Helpers::Form |
| In: |
merb-helpers/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).
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 19
19: def _new_form_context(name, builder)
20: if name.is_a?(String) || name.is_a?(Symbol)
21: ivar = instance_variable_get("@#{name}")
22: else
23: ivar, name = name, name.class.to_s.snake_case
24: end
25: builder ||= current_form_context.class if current_form_context
26: (builder || self._default_builder).new(ivar, name, self)
27: end
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 5 5: def _singleton_form_context 6: self._default_builder = Merb::Helpers::Form::Builder::ResourcefulFormWithErrors unless self._default_builder 7: @_singleton_form_context ||= 8: self._default_builder.new(nil, nil, self) 9: end
Generates a HTML button.
| contents<String>: | HTML contained within the button tag |
| attrs<Hash>: | HTML attributes |
| String: | HTML |
* 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/
<%= button "Initiate Launch Sequence" %>
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 374
374: def button(contents, attrs = {})
375: current_form_context.button(contents, attrs)
376: 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.
| method<Symbol>: | Resource attribute |
| attrs<Hash>: | HTML attributes and options |
| String: | HTML |
<%= 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 merb-helpers/lib/merb-helpers/form/helpers.rb, line 175
175: def check_box; end
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 15
15: def current_form_context
16: form_contexts.last || _singleton_form_context
17: end
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
| 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 |
| String: | HTML |
<%= delete_button @article, "Delete article now", :class => 'delete-btn' %> <%= delete_button url(:article, @article)%>
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 395
395: def delete_button(object_or_url, contents="Delete", attrs = {})
396: url = object_or_url.is_a?(String) ? object_or_url : resource(object_or_url)
397: button_text = (contents || 'Delete')
398: tag :form, :class => 'delete-btn', :action => url, :method => :post do
399: tag(:input, :type => :hidden, :name => "_method", :value => "DELETE") <<
400: tag(:input, attrs.merge(:value => button_text, :type => :submit))
401: end
402: end
Provides a HTML formatted display of resource errors in an unordered list with a h2 form submission error
| 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 |
| String: | HTML |
<%= 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 merb-helpers/lib/merb-helpers/form/helpers.rb, line 436
436: def error_messages_for(obj = nil, opts = {})
437: current_form_context.error_messages_for(obj, opts[:error_class] || "error",
438: opts[:build_li] || "<li>%s</li>",
439: opts[:header] || "<h2>Form submission failed because of %s problem%s</h2>",
440: opts.key?(:before) ? opts[:before] : true)
441: 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.
<%= 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 merb-helpers/lib/merb-helpers/form/helpers.rb, line 111
111: def fields_for(name, attrs = {}, &blk)
112: attrs ||= {}
113: with_form_context(name, attrs.delete(:builder)) do
114: capture(&blk)
115: end
116: end
Provides the ability to create quick fieldsets as blocks for your forms.
| attrs<Hash>: | HTML attributes and options |
| legend: | Adds a legend tag within the fieldset |
| String: | HTML |
Block helpers use the <%= =%> syntax
<%= fieldset :legend => "Customer Options" do %>
...your form elements
<% end =%>
Generates the HTML:
<fieldset>
<legend>Customer Options</legend>
...your form elements
</fieldset>
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 143
143: def fieldset(attrs = {}, &blk)
144: _singleton_form_context.fieldset(attrs, &blk)
145: end
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 147
147: def fieldset_for(name, attrs = {}, &blk)
148: with_form_context(name, attrs.delete(:builder)) do
149: current_form_context.fieldset(attrs, &blk)
150: end
151: end
Provides a HTML file input
| name<Symbol>: | Model or Resource |
| attrs<Hash>: | HTML attributes |
| String: | HTML |
<%= file_field :name => "file", :label => "File" %>
Used with a model:
<%= file_field :file, :label => "Choose a file" %>
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 192
192: def file_field; end
Generates a form tag, which accepts a block that is not directly based on resource attributes
| attrs<Hash>: | HTML attributes |
| String: | HTML |
* Block helpers use the <%= =%> syntax * a multipart enctype is automatically set if the form contains a file upload field
<%= 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 merb-helpers/lib/merb-helpers/form/helpers.rb, line 61
61: def form(*args, &blk)
62: _singleton_form_context.form(*args, &blk)
63: end
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 11
11: def form_contexts
12: @_form_contexts ||= []
13: end
Generates a resource specific form tag which accepts a block, this also provides automatic resource routing.
| name<Symbol>: | Model or Resource |
| attrs<Hash>: | HTML attributes |
| String: | HTML |
* Block helpers use the <%= =%> syntax
<%= 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 merb-helpers/lib/merb-helpers/form/helpers.rb, line 93
93: def form_for(name, attrs = {}, &blk)
94: with_form_context(name, attrs.delete(:builder)) do
95: current_form_context.form(attrs, &blk)
96: end
97: end
Provides a HTML hidden input field
| name<Symbol>: | Model or Resource |
| attrs<Hash>: | HTML attributes |
| String: | HTML |
<%= 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}" />
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 210
210: def hidden_field; end
Provides a generic HTML label.
| attrs<Hash>: | HTML attributes |
| String: | HTML |
<%= label "Full Name", :for => "name" %> => <label for="name">Full Name</label>
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 223
223: def label(*args)
224: current_form_context.label(*args)
225: end
Provides a HTML password input.
| name<Symbol>: | Model or Resource |
| attrs<Hash>: | HTML attributes |
| String: | HTML |
<%= 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 merb-helpers/lib/merb-helpers/form/helpers.rb, line 243
243: def password_field; end
Provides a HTML radio input tag
| method<Symbol>: | Resource attribute |
| attrs<Hash>: | HTML attributes and options |
| String: | HTML |
<%= 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 =%>
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 264
264: def radio_button; end
Provides a radio group based on a resource attribute. This is generally used within a resource block such as form_for.
| method<Symbol>: | Resource attribute |
| arr<Array>: | Choices |
| String: | HTML |
<%# the labels are the options %>
<%= radio_group :my_choice, [5,6,7] %>
<%# custom labels %>
<%= radio_group :my_choice, [{:value => 5, :label => "five"}] %>
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 282
282: def radio_group; end
Provides a HTML select
| method<Symbol>: | Resource attribute |
| attrs<Hash>: | HTML attributes and 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). |
| String: | HTML |
<%= select :name, :collection => %w(one two three) %>
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 303
303: def select; end
Generates a HTML submit button.
| value<String>: | Sets the value="" attribute |
| attrs<Hash>: | HTML attributes |
| String: | HTML |
<%= submit "Process" %>
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 415
415: def submit(contents, attrs = {})
416: current_form_context.submit(contents, attrs)
417: end
Provides a HTML textarea tag
| contents<String>: | Contents of the text area |
| attrs<Hash>: | HTML attributes |
| String: | HTML |
<%= text_area "my comments", :name => "comments" %>
Used with a model:
<%= text_area :comments %>
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 320
320: def text_area; end
Provides a HTML text input tag
| name<Symbol>: | Model or Resource |
| attrs<Hash>: | HTML attributes |
| String: | HTML |
<%= 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 merb-helpers/lib/merb-helpers/form/helpers.rb, line 340
340: def text_field; end
# File merb-helpers/lib/merb-helpers/form/helpers.rb, line 29
29: def with_form_context(name, builder)
30: form_contexts.push(_new_form_context(name, builder))
31: ret = yield
32: form_contexts.pop
33: ret
34: end