Module: Merb::Helpers::Form

Included in:
Controller, PartController
Defined in:
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

#_new_form_context(name, builder) ⇒ Object 



19
20
21
22
23
24
25
26
27
 
# 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
  end
  builder ||= current_form_context.class if current_form_context
  (builder || self._default_builder).new(ivar, name, self)
end

#_singleton_form_context ⇒ Object 



5
6
7
8
9
 
# 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

#button(contents, attrs = {}) ⇒ Object

Generates a HTML button.

Parameters

contents

HTML contained within the button tag

attrs

HTML attributes

Returns

String

HTML

Notes

Example

<%= button "Initiate Launch Sequence" %>



373
374
375
 
# File 'lib/merb_helpers/form/helpers.rb', line 373

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

#check_box ⇒ Object

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

Resource attribute

attrs

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


175
 
# File 'lib/merb_helpers/form/helpers.rb', line 175

def check_box; end

#current_form_context ⇒ Object 



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

def current_form_context
  form_contexts.last || _singleton_form_context
end

#error_messages_for(obj = nil, opts = {}) ⇒ Object Also known as: error_messages

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

Parameters

obj

Model or Resource

error_class

CSS class to use for error container

build_li

Custom li tag to wrap each error in

header

Custom header text for the error container

before

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

  • #{error.join(' ')}"} %> <%= error_messages_for :person, nil, 'bad_mojo' %>

    • 

409
410
411
412
413
414
    		 
    # File 'lib/merb_helpers/form/helpers.rb', line 409

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

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

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

    

111
112
113
114
115
116
    		 
    # File 'lib/merb_helpers/form/helpers.rb', line 111

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

    #fieldset(attrs = {}, &blk) ⇒ Object

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

    Parameters

    attrs

    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:

    Customer Options ...your form elements 
    

143
144
145
    		 
    # File 'lib/merb_helpers/form/helpers.rb', line 143

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

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

    

147
148
149
150
151
    		 
    # 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

    #file_field ⇒ Object

    Provides a HTML file input

    Parameters

    name

    Model or Resource

    attrs

    HTML attributes

    Returns

    String

    HTML

    Example

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

    Used with a model:

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

192
    		 
    # File 'lib/merb_helpers/form/helpers.rb', line 192

def file_field; end

    #form(*args, &blk) ⇒ Object

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

    Parameters

    attrs

    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:

    

61
62
63
    		 
    # File 'lib/merb_helpers/form/helpers.rb', line 61

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

    #form_contexts ⇒ Object 

    

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

def form_contexts
  @_form_contexts ||= []
end

    #form_for(name, attrs = {}, &blk) ⇒ Object

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

    Parameters

    name

    Model or Resource

    attrs

    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:

    

93
94
95
96
97
    		 
    # 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

    #hidden_field ⇒ Object

    Provides a HTML hidden input field

    Parameters

    name

    Model or Resource

    attrs

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

210
    		 
    # File 'lib/merb_helpers/form/helpers.rb', line 210

def hidden_field; end

    #label(*args) ⇒ Object

    Provides a generic HTML label.

    Parameters

    attrs

    HTML attributes

    Returns

    String

    HTML

    Example

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

    

223
224
225
    		 
    # File 'lib/merb_helpers/form/helpers.rb', line 223

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

    #password_field ⇒ Object

    Provides a HTML password input.

    Parameters

    name

    Model or Resource

    attrs

    HTML attributes

    Returns

    String

    HTML

    Example

    <%= password_field :name => :password, :label => "Password" %>

    =>

    Used with a model:

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

243
    		 
    # File 'lib/merb_helpers/form/helpers.rb', line 243

def password_field; end

    #radio_button ⇒ Object

    Provides a HTML radio input tag

    Parameters

    method

    Resource attribute

    attrs

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

264
    		 
    # File 'lib/merb_helpers/form/helpers.rb', line 264

def radio_button; end

    #radio_group ⇒ Object

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

    Parameters

    method

    Resource attribute

    arr

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

282
    		 
    # File 'lib/merb_helpers/form/helpers.rb', line 282

def radio_group; end

    #select ⇒ Object

    Provides a HTML select

    Parameters

    method

    Resource attribute

    attrs

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

    

303
    		 
    # File 'lib/merb_helpers/form/helpers.rb', line 303

def select; end

    #submit(contents, attrs = {}) ⇒ Object

    Generates a HTML submit button.

    Parameters

    value

    Sets the value="" attribute

    attrs

    HTML attributes

    Returns

    String

    HTML

    Example

    <%= submit "Process" %>

    

388
389
390
    		 
    # File 'lib/merb_helpers/form/helpers.rb', line 388

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

    #text_area ⇒ Object

    Provides a HTML textarea tag

    Parameters

    contents

    Contents of the text area

    attrs

    HTML attributes

    Returns

    String

    HTML

    Example

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

    Used with a model:

    <%= text_area :comments %>
    

320
    		 
    # File 'lib/merb_helpers/form/helpers.rb', line 320

def text_area; end

    #text_field ⇒ Object

    Provides a HTML text input tag

    Parameters

    name

    Model or Resource

    attrs

    HTML attributes

    Returns

    String

    HTML

    Example

    <%= text_field :name => :fav_color, :label => "Your Favorite Color" %>

    =>

    Used with a model:

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

340
    		 
    # File 'lib/merb_helpers/form/helpers.rb', line 340

def text_field; end

    #with_form_context(name, builder) ⇒ Object 

    

29
30
31
32
33
34
    		 
    # 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