HTML::FormFu::Element:UsereContributed PerHTML::FormFu::Element::Repeatable(3)NAMEHTML::FormFu::Element::Repeatable - repeatable block element
SYNOPSIS---
elements:
- type: Repeatable
name: my_rep
elements:
- name: foo
- name: bar
Calling "$element->repeat(2)" would result in the following markup:
<div>
<input name="my_rep.foo_1" type="text" />
<input name="my_rep.bar_1" type="text" />
</div>
<div>
<input name="my_rep.foo_2" type="text" />
<input name="my_rep.bar_2" type="text" />
</div>
Example of constraints:
----
elements:
- type: Repeatable
name: my_rep
elements:
- name: id
- name: foo
constraints:
- type: Required
when:
field: 'my_rep.id' # use full nested-name
- name: bar
constraints:
- type: Equal
others: 'my_rep.foo' # use full nested-name
DESCRIPTION
Provides a way to extend a form at run-time, by copying and repeating
its child elements.
The elements intended for copying must be added before "repeat" is
called.
Although the Repeatable element inherits from Block, it doesn't
generate a block tag around all the repeated elements - instead it
places each repeat of the elements in a new Block element, which
inherits the Repeatable's display settings, such as "attributes" and
"tag".
For all constraints attached to fields within a Repeatable block which
use either others or when containing names of fields within the same
Repeatable block, when repeat is called, those names will automatically
be updated to the new nested-name for each field (taking into account
increment_field_names).
METHODS
repeat
Arguments: [$count]
Return Value: $arrayref_of_new_child_blocks
This method creates $count number of copies of the child elements. If
no argument $count is provided, it defaults to 1.
Note that "$form->process" will call "repeat" automatically to ensure
the initial child elements are correctly set up - unless you call
"repeat" manually first, in which case the child elements you created
will be left untouched (otherwise process would overwrite your
changes).
Any subsequent call to "repeat" will delete the previously copied
elements before creating new copies - this means you cannot make
repeated calls to "repeat" within a loop to create more copies.
Each copy of the elements returned are contained in a new Block
element. For example, calling "$element->repeat(2)" on a Repeatable
element containing 2 Text fields would return 2 Block elements, each
containing a copy of the 2 Text fields.
counter_name
Arguments: $name
If true, the "query" in HTML::FormFu will be searched during "process"
in HTML::FormFu for a parameter with the given name. The value for that
parameter will be passed to "repeat", to automatically create the new
copies.
If "increment_field_names" is true (the default), this is essential: if
the elements corresponding to the new fieldnames (foo_1, bar_2, etc.)
are not present on the form during "process" in HTML::FormFu, no
Processors (Constraints, etc.) will be run on the fields, and their
values will not be returned by "params" in HTML::FormFu or "param" in
HTML::FormFu.
increment_field_names
Arguments: $bool
Default Value: 1
If true, then all fields will have "_n" appended to their name, where
"n" is the "repeatable_count" value.
repeatable_count
This is set on each new Block element returned by "repeat", starting at
number 1.
Because this is an 'inherited accessor' available on all elements, it
can be used to determine whether any element is a child of a Repeatable
element.
Only available after repeat has been called.
nested_name
If the "nested_name" attribute is set, the naming scheme of the
Repeatable element's children is switched to add the counter to the
repeatable blocks themselves.
---
elements:
- type: Repeatable
nested_name: my_rep
elements:
- name: foo
- name: bar
Calling "$element->repeat(2)" would result in the following markup:
<div>
<input name="my_rep_1.foo" type="text" />
<input name="my_rep_1.bar" type="text" />
</div>
<div>
<input name="my_rep_2.foo" type="text" />
<input name="my_rep_2.bar" type="text" />
</div>
Because this is an 'inherited accessor' available on all elements, it
can be used to determine whether any element is a child of a Repeatable
element.
attributes
attrs
Any attributes set will be passed to every repeated Block of elements.
---
elements:
- type: Repeatable
name: my_rep
attributes:
class: rep
elements:
- name: foo
Calling "$element->repeat(2)" would result in the following markup:
<div class="rep">
<input name="my_rep.foo_1" type="text" />
</div>
<div class="rep">
<input name="my_rep.foo_2" type="text" />
</div>
See "attributes" in HTML::FormFu for details.
tag
The "tag" value will be passed to every repeated Block of elements.
---
elements:
- type: Repeatable
name: my_rep
tag: span
elements:
- name: foo
Calling "$element->repeat(2)" would result in the following markup:
<span>
<input name="my_rep.foo_1" type="text" />
</span>
<span>
<input name="my_rep.foo_2" type="text" />
</span>
See "tag" in HTML::FormFu::Element::Block for details.
auto_id
As well as the usual subtitutions, any instances of %r will be replaced
with the value of "repeatable_count".
See "auto_id" in HTML::FormFu::Element::Block for further details.
---
elements:
- type: Repeatable
name: my_rep
auto_id: "%n_%r"
elements:
- name: foo
Calling "$element->repeat(2)" would result in the following markup:
<div>
<input name="my_rep.foo_1" id="foo_1" type="text" />
</div>
<div>
<input name="my_rep.foo_2" id="foo_2" type="text" />
</div>
content
Not supported for Repeatable elements - will throw a fatal error if
called as a setter.
CAVEATS
Unsupported Constraints
Note that constraints with an others method do not work correctly
within a Repeatable block. Currently, these are: AllOrNone, DependOn,
Equal, MinMaxFields, reCAPTCHA. Also, the CallbackOnce constraint
won't work within a Repeatable block, as it wouldn't make much sense.
SEE ALSO
Is a sub-class of, and inherits methods from
HTML::FormFu::Element::Block, HTML::FormFu::Element
HTML::FormFu
AUTHOR
Carl Franks, "cfranks@cpan.org"
LICENSE
This library is free software, you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.22012-01-HTML::FormFu::Element::Repeatable(3)
