class Forme::Form

  1. lib/forme/form.rb
Superclass: Object

The Form class is the main entry point to the library.

Using the form, input, tag, and inputs methods, one can return HTML form tag string (or fragments of an HTML form tag).

Attributes

form_tag_attributes [R]

The attributes used for the form tag for this form.

hidden_tags [R]

The hidden tags to automatically add to the form.

input_defaults [R]

Set the default options for inputs by type. This should be a hash with input type keys and values that are hashes of input options.

opts [R]

A hash of options for the form.

serializer [R]

The serializer determines how Tag objects are transformed into strings. Must respond to call or be a registered symbol.

to_s [R]

The contents of the form as a string. This should not be mutated by external code.

Public Class methods

form(obj=nil, attr={}, opts={}, &block)

Create a Form instance and yield it to the block. Returns an HTML string for the form tag.

Argument Handling:

No args

Creates a Form object with no options and not associated to an obj, and with no attributes in the opening tag.

1 hash arg

Treated as opening form tag attributes, creating a Form object with no options.

1 non-hash arg

Treated as the Form's obj, with empty options and no attributes in the opening tag.

2 hash args

First hash is opening attributes, second hash is Form options.

1 non-hash arg, 1-2 hash args

First argument is Form's obj, second is opening attributes, third if provided is Form's options.

[show source]
   # File lib/forme/form.rb
79 def self.form(obj=nil, attr={}, opts={}, &block)
80   f, attr, block = form_args(obj, attr, opts, &block)
81   f.form(attr, &block)
82 end
form_args(obj, attr, opts, &block)

Parse the args given to form and return Form instance, form tag attributes, and block for form.

[show source]
   # File lib/forme/form.rb
41 def self.form_args(obj, attr, opts, &block)
42   f = if obj.is_a?(Hash)
43     raise Error, "Can't provide 3 hash arguments to form" unless opts.empty?
44     opts = attr
45     attr = obj
46     new(opts)
47   else
48     new(obj, opts)
49   end
50 
51   ins = opts[:inputs]
52   button = opts[:button]
53   if ins || button
54     block = proc do |form|
55       form.inputs(ins, opts) if ins
56       yield form if block_given?
57       form.button(button) if button
58     end
59   end
60 
61   [f, attr, block]
62 end
new(obj=nil, opts={})

Use appropriate Form subclass for object based on the current class, if the object responds to forme_form_class.

[show source]
   # File lib/forme/form.rb
31 def self.new(obj=nil, opts={})
32   if obj && obj.respond_to?(:forme_form_class) && !opts[:_forme_form_class_set]
33     obj.forme_form_class(self).new(obj, opts.merge(:_forme_form_class_set=>true))
34   else
35     super
36   end
37 end
new(obj=nil, opts={})

Creates a Form object. Arguments:

obj

Sets the obj for the form. If a hash, is merged with the opts argument to set the opts.

opts

A hash of options for the form

[show source]
    # File lib/forme/form.rb
 88 def initialize(obj=nil, opts={})
 89   @opts = opts.merge(obj.is_a?(Hash) ? obj : {:obj=>obj})
 90   @opts[:namespace] = Array(@opts[:namespace])
 91 
 92   if obj && obj.respond_to?(:forme_config)
 93     obj.forme_config(self)
 94   end
 95 
 96   config = CONFIGURATIONS[@opts[:config]||Forme.default_config]
 97   copy_inputs_wrapper_from_wrapper(@opts)
 98 
 99   TRANSFORMER_TYPES.each do |t|
100     case @opts[t]
101     when Symbol
102       @opts[t] = Forme.transformer(t, @opts[t], @opts)
103     when nil
104       unless @opts.has_key?(t)
105         @opts[t] = Forme.transformer(t, config, @opts)
106       end
107     end
108   end
109 
110   @serializer = @opts[:serializer]
111   @input_defaults = @opts[:input_defaults] || {}
112   @hidden_tags = @opts[:hidden_tags]
113   if @hidden_tags && !@hidden_tags.empty? && RUBY_VERSION >= '2'
114     uplevel = 6
115     uplevel += @opts[:hidden_tags_uplevel] if @opts[:hidden_tags_uplevel]
116     warn("The Forme::Form :hidden_tags option is deprecated, please switch to using the :before option", :uplevel=>uplevel)
117   end
118   @to_s = String.new
119 end

Public Instance methods

<<(tag)

Add the Input/Tag instance to the HTML buffer.

[show source]
    # File lib/forme/form.rb
309 def <<(tag)
310   @to_s << tag.to_s
311 end
_input(*a)

Return a new Input associated with the receiver with the given arguments, doing no other processing.

[show source]
    # File lib/forme/form.rb
190 def _input(*a)
191   Input.new(self, *a)
192 end
_tag(*a, &block)

Create a Tag associated to the receiver with the given arguments and block, doing no other processing.

[show source]
    # File lib/forme/form.rb
265 def _tag(*a, &block)
266   Tag.new(self, *a, &block)
267 end
button(opts={})

Creates a :submit Input with the given opts. Returns the generated HTML for the input.

[show source]
    # File lib/forme/form.rb
303 def button(opts={})
304   opts = {:value=>opts} if opts.is_a?(String)
305   content_added{self << _input(:submit, opts)}
306 end
close()

Returns a string representing the closing of the form tag, for serializers that support closing tags.

[show source]
    # File lib/forme/form.rb
259 def close
260   serializer.serialize_close(_tag(:form)) if serializer.respond_to?(:serialize_close)
261 end
each_obj(objs, namespace=nil)

Calls the block for each object in objs, using with_obj with the given namespace and an index namespace (starting at 0).

[show source]
    # File lib/forme/form.rb
315 def each_obj(objs, namespace=nil)
316   objs.each_with_index do |obj, i|
317     with_obj(obj, Array(namespace) + [i]) do
318       yield obj, i
319     end
320   end
321 end
form(attr={})

Create a form tag with the given attributes. Returns an HTML string for the generated form tag.

[show source]
    # File lib/forme/form.rb
123 def form(attr={})
124   if obj && !attr[:method] && !attr['method'] && obj.respond_to?(:forme_default_request_method)
125     attr = Hash[attr]
126     attr['method'] = obj.forme_default_request_method
127   end
128   @form_tag_attributes = attr
129 
130   tag(:form, attr, method(:hidden_form_tags)) do
131     before_form_yield
132     yield self if block_given?
133     after_form_yield
134   end
135 end
input(field, opts={})

Creates an Input with the given field and opts associated with the receiver. Returns the HTML generated by the given input.

If the form is associated with an obj, or the :obj key exists in the opts argument, treats the field as a call to the obj. If obj responds to forme_input, that method is called with the field and a copy of opts. Otherwise, the field is used as a method call on the obj and a text input is created with the result.

If no obj is associated with the receiver, field represents an input type (e.g. :text, :textarea, :select), and an input is created directly with the field and opts.

[show source]
    # File lib/forme/form.rb
155 def input(field, opts={})
156   content_added do
157     if opts.has_key?(:obj)
158       opts = opts.dup
159       obj = opts.delete(:obj)
160     else
161       obj = self.obj
162     end
163 
164     input = if obj
165       if obj.respond_to?(:forme_input)
166         obj.forme_input(self, field, opts.dup)
167       else
168         opts = opts.dup
169         opts[:key] = field unless opts.has_key?(:key)
170         type = opts.delete(:type) || :text
171         unless opts.has_key?(:value) || type == :file
172           opts[:value] = if obj.is_a?(Hash)
173             obj[field]
174           else
175             obj.send(field)
176           end
177         end
178         _input(type, opts)
179       end
180     else
181       _input(field, opts)
182     end
183 
184     self << input
185   end
186 end
inputs(inputs=[], opts={})

Creates a tag using the inputs_wrapper (a fieldset by default), calls input on each element of inputs, and yields if given a block. You can use array arguments if you want inputs to be created with specific options:

f.inputs([:field1, :field2])
f.inputs([[:field1, {:name=>'foo'}], :field2])

The given opts are passed to the inputs_wrapper, and the default inputs_wrapper supports a :legend option that is used to set the legend for the fieldset.

opts can also include transformer options itself (e.g. :wrapper), which override the form's current transformer options for the duration of the block. The exception is the :inputs_wrapper transformer option, which affects the wrapper to use for this inputs call. You can use the :nested_inputs_wrapper option to set the default :inputs_wrapper option for the duration of the block.

Returns the HTML generated by the inputs added to the form.

This can also be called with a single hash argument to just use an options hash:

f.inputs(:legend=>'Foo') do
  # ...
end

or even without any arguments:

f.inputs do
  # ...
end
[show source]
    # File lib/forme/form.rb
225 def inputs(inputs=[], opts={})
226   content_added do
227     if inputs.is_a?(Hash)
228       opts = inputs.merge(opts)
229       inputs = []
230     end
231 
232     form_opts = {}
233     form_opts[:inputs_wrapper] = opts[:nested_inputs_wrapper] if opts[:nested_inputs_wrapper]
234     TRANSFORMER_TYPES.each do |t|
235       if opts.has_key?(t) && t != :inputs_wrapper
236         form_opts[t] = opts[t]
237       end
238     end
239 
240     Forme.transform(:inputs_wrapper, opts, @opts, self, opts) do
241       with_opts(form_opts) do
242         inputs.each do |i|
243           input(*i)
244         end
245         yield if block_given?
246       end
247     end
248   end
249 end
namespaces()

The namespaces if any for the receiver's inputs. This can be used to automatically setup namespaced class and id attributes.

[show source]
    # File lib/forme/form.rb
278 def namespaces
279   @opts[:namespace]
280 end
obj()

The object associated with this form, if any. If the Form has an associated obj, then calls to input are assumed to be accessing fields of the object instead to directly representing input types.

[show source]
    # File lib/forme/form.rb
272 def obj
273   @opts[:obj]
274 end
open(attr)

Returns a string representing the opening of the form tag for serializers that support opening tags.

[show source]
    # File lib/forme/form.rb
253 def open(attr)
254   serializer.serialize_open(_tag(:form, attr)) if serializer.respond_to?(:serialize_open)
255 end
post?()

Whether the method for this form is POST. Only callable after calling form.

[show source]
    # File lib/forme/form.rb
139 def post?
140   (form_tag_attributes[:method] || form_tag_attributes['method']).to_s.upcase == 'POST'
141 end
raw(s)

Return a new string that will not be HTML escaped by the default serializer.

[show source]
    # File lib/forme/form.rb
324 def raw(s)
325   Forme.raw(s)
326 end
tag(*a, &block)

Creates a Tag associated to the receiver with the given arguments. If a block is given, yield to the block inside the generated tag. Returns the HTML added to the form by the addition of this tag.

[show source]
    # File lib/forme/form.rb
285 def tag(*a, &block)
286   content_added do
287     tag = _tag(*a)
288     if block
289       self << serialize_open(tag)
290       if children = tag.children
291         children.each{|child| self << child}
292       end
293       yield self
294       self << serialize_close(tag)
295     else
296       self << tag
297     end
298   end
299 end
with_obj(obj, namespace=nil)

Temporarily override the given object and namespace for the form. Any given namespaces are appended to the form's current namespace.

[show source]
    # File lib/forme/form.rb
330 def with_obj(obj, namespace=nil)
331   with_opts(:obj=>obj, :namespace=>@opts[:namespace]+Array(namespace)) do
332     yield obj
333   end
334 end
with_opts(opts)

Temporarily override the opts for the form for the duration of the block. This merges the given opts with the form's current opts, restoring the previous opts before returning.

[show source]
    # File lib/forme/form.rb
339 def with_opts(opts)
340   orig_opts = @opts
341   @opts = orig_opts.merge(opts)
342   copy_inputs_wrapper_from_wrapper(opts, @opts)
343   yield
344 ensure
345   @opts = orig_opts if orig_opts
346 end