NAME

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

VERSION

       version 2.07

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.

   repeatable_count_no_inherit
       A non-inheriting variant of "repeatable_count".

   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 substitutions, 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.

   Work-arounds
       See HTML::FormFu::Filter::ForceListValue to address a problem with increment_field_names
       disabled, and increading the repeat on the server-side.

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.

AUTHOR

       Carl Franks <cpan@fireartist.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2018 by Carl Franks.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.