NAME

HTML::FormFu::Element::Repeatable - repeatable block element

SYNOPSIS

---
elements:
  - type: Repeatable
    elements:
      - name: foo
      - name: bar

Calling $element->repeat(2) would result in the following markup:

<div>
    <input name="foo" type="text" />
    <input name="bar" type="text" />
</div>
<div>
    <input name="foo" type="text" />
    <input name="bar" type="text" />
</div>

DESCRIPTION

Provides a way to extend a form at run-time, by copying and repeating it's 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".

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.

"repeat" is automatically called during $form->process, to ensure the initial child elements are correctly setup.

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 any copies of fields whose name contains a 0, will have the 0 replaced by it's "repeatable_count" value.

---
elements:
  - type: Repeatable
    increment_field_names: 1
    elements:
      - name: foo_0
      - name: bar_0

Calling $element->repeat(2) would result in the following markup:

<div>
    <input name="foo_1" type="text" />
    <input name="bar_1" type="text" />
</div>
<div>
    <input name="foo_2" type="text" />
    <input name="bar_2" type="text" />
</div>

See also "counter_name".

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.

attributes

attrs

Any attributes set will be passed to every repeated Block of elements.

---
elements:
  - type: Repeatable
    attributes: 
      class: rep
    elements:
      - name: foo

Calling $element->repeat(2) would result in the following markup:

<div class="rep">
    <input name="foo" type="text" />
</div>
<div class="rep">
    <input name="foo" 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
    tag: span
    elements:
      - name: foo

Calling $element->repeat(2) would result in the following markup:

<span>
    <input name="foo" type="text" />
</span>
<span>
    <input name="foo" 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
    auto_id: "%n_%r"
    elements:
      - name: foo

Calling $element->repeat(2) would result in the following markup:

<div>
    <input name="foo" id="foo_1" type="text" />
</div>
<div>
    <input name="foo" id="foo_2" type="text" />
</div>

content

Not supported for Repeatable elements - will throw a fatal error if called as a setter.

SEE ALSO

Is a sub-class of, and inherits methods from HTML::FormFu::Element::Block, HTML::FormFu::Element

HTML::FormFu::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.