.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "HTML::FormFu::Element::Repeatable 3pm"
.TH HTML::FormFu::Element::Repeatable 3pm "2014-05-05" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTML::FormFu::Element::Repeatable \- repeatable block element
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\&    \-\-\-
\&    elements:
\&      \- type: Repeatable
\&        name: my_rep
\&        elements:
\&          \- name: foo
\&          \- name: bar
.Ve
.PP
Calling \f(CW\*(C`$element\->repeat(2)\*(C'\fR would result in the following markup:
.PP
.Vb 8
\&    <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>
.Ve
.PP
Example of constraints:
.PP
.Vb 6
\&    \-\-\-\-
\&    elements:
\&      \- type: Repeatable
\&        name: my_rep
\&        elements:
\&          \- name: id
\&
\&          \- name: foo
\&            constraints:
\&              \- type: Required
\&                when:
\&                  field: \*(Aqmy_rep.id\*(Aq # use full nested\-name
\&
\&          \- name: bar
\&            constraints:
\&              \- type: Equal
\&                others: \*(Aqmy_rep.foo\*(Aq # use full nested\-name
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides a way to extend a form at run-time, by copying and repeating its
child elements.
.PP
The elements intended for copying must be added before \*(L"repeat\*(R" is called.
.PP
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 \*(L"attributes\*(R" and
\&\*(L"tag\*(R".
.PP
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).
.SH "METHODS"
.IX Header "METHODS"
.SS "repeat"
.IX Subsection "repeat"
Arguments: [$count]
.PP
Return Value: \f(CW$arrayref_of_new_child_blocks\fR
.PP
This method creates \f(CW$count\fR number of copies of the child elements.
If no argument \f(CW$count\fR is provided, it defaults to \f(CW1\fR.
.PP
Note that \f(CW\*(C`$form\->process\*(C'\fR will call \*(L"repeat\*(R" automatically to ensure the
initial child elements are correctly set up \- unless you call \*(L"repeat\*(R"
manually first, in which case the child elements you created will be left
untouched (otherwise process would overwrite your
changes).
.PP
Any subsequent call to \*(L"repeat\*(R" will delete the previously copied elements
before creating new copies \- this means you cannot make repeated calls to
\&\*(L"repeat\*(R" within a loop to create more copies.
.PP
Each copy of the elements returned are contained in a new
Block element. For example, calling
\&\f(CW\*(C`$element\->repeat(2)\*(C'\fR on a Repeatable element containing 2 Text fields
would return 2 Block elements, each
containing a copy of the 2 Text fields.
.SS "counter_name"
.IX Subsection "counter_name"
Arguments: \f(CW$name\fR
.PP
If true, the \*(L"query\*(R" in HTML::FormFu will be searched during
\&\*(L"process\*(R" in HTML::FormFu for a parameter with the given name. The value for
that parameter will be passed to \*(L"repeat\*(R", to automatically create the
new copies.
.PP
If \*(L"increment_field_names\*(R" 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 \*(L"process\*(R" in HTML::FormFu, no Processors
(Constraints, etc.) will be run on the fields, and their values will not
be returned by \*(L"params\*(R" in HTML::FormFu or \*(L"param\*(R" in HTML::FormFu.
.SS "increment_field_names"
.IX Subsection "increment_field_names"
Arguments: \f(CW$bool\fR
.PP
Default Value: 1
.PP
If true, then all fields will have \f(CW\*(C`_n\*(C'\fR appended to their name, where
\&\f(CW\*(C`n\*(C'\fR is the \*(L"repeatable_count\*(R" value.
.SS "repeatable_count"
.IX Subsection "repeatable_count"
This is set on each new Block element
returned by \*(L"repeat\*(R", starting at number \f(CW1\fR.
.PP
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.
.PP
Only available after repeat has been called.
.SS "repeatable_count_no_inherit"
.IX Subsection "repeatable_count_no_inherit"
A non-inheriting variant of \*(L"repeatable_count\*(R".
.SS "nested_name"
.IX Subsection "nested_name"
If the \*(L"nested_name\*(R" attribute is set, the naming scheme of the Repeatable
element's children is switched to add the counter to the repeatable blocks
themselves.
.PP
.Vb 7
\&    \-\-\-
\&    elements:
\&      \- type: Repeatable
\&        nested_name: my_rep
\&        elements:
\&          \- name: foo
\&          \- name: bar
.Ve
.PP
Calling \f(CW\*(C`$element\->repeat(2)\*(C'\fR would result in the following markup:
.PP
.Vb 8
\&    <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>
.Ve
.PP
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.
.SS "attributes"
.IX Subsection "attributes"
.SS "attrs"
.IX Subsection "attrs"
Any attributes set will be passed to every repeated Block of elements.
.PP
.Vb 8
\&    \-\-\-
\&    elements:
\&      \- type: Repeatable
\&        name: my_rep
\&        attributes:
\&          class: rep
\&        elements:
\&          \- name: foo
.Ve
.PP
Calling \f(CW\*(C`$element\->repeat(2)\*(C'\fR would result in the following markup:
.PP
.Vb 6
\&    <div class="rep">
\&        <input name="my_rep.foo_1" type="text" />
\&    </div>
\&    <div class="rep">
\&        <input name="my_rep.foo_2" type="text" />
\&    </div>
.Ve
.PP
See \*(L"attributes\*(R" in HTML::FormFu for details.
.SS "tag"
.IX Subsection "tag"
The \*(L"tag\*(R" value will be passed to every repeated Block of elements.
.PP
.Vb 7
\&    \-\-\-
\&    elements:
\&      \- type: Repeatable
\&        name: my_rep
\&        tag: span
\&        elements:
\&          \- name: foo
.Ve
.PP
Calling \f(CW\*(C`$element\->repeat(2)\*(C'\fR would result in the following markup:
.PP
.Vb 6
\&    <span>
\&        <input name="my_rep.foo_1" type="text" />
\&    </span>
\&    <span>
\&        <input name="my_rep.foo_2" type="text" />
\&    </span>
.Ve
.PP
See \*(L"tag\*(R" in HTML::FormFu::Element::Block for details.
.SS "auto_id"
.IX Subsection "auto_id"
As well as the usual subtitutions, any instances of \f(CW%r\fR will be
replaced with the value of \*(L"repeatable_count\*(R".
.PP
See \*(L"auto_id\*(R" in HTML::FormFu::Element::Block for further details.
.PP
.Vb 7
\&    \-\-\-
\&    elements:
\&      \- type: Repeatable
\&        name: my_rep
\&        auto_id: "%n_%r"
\&        elements:
\&          \- name: foo
.Ve
.PP
Calling \f(CW\*(C`$element\->repeat(2)\*(C'\fR would result in the following markup:
.PP
.Vb 6
\&    <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>
.Ve
.SS "content"
.IX Subsection "content"
Not supported for Repeatable elements \- will throw a fatal error if called as
a setter.
.SH "CAVEATS"
.IX Header "CAVEATS"
.SS "Unsupported Constraints"
.IX Subsection "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.
.SS "Work-arounds"
.IX Subsection "Work-arounds"
See HTML::FormFu::Filter::ForceListValue to address a problem with 
increment_field_names disabled, and increading the repeat on the
server-side.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Is a sub-class of, and inherits methods from
HTML::FormFu::Element::Block,
HTML::FormFu::Element
.PP
HTML::FormFu
.SH "AUTHOR"
.IX Header "AUTHOR"
Carl Franks, \f(CW\*(C`cfranks@cpan.org\*(C'\fR
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software, you can redistribute it and/or modify it under
the same terms as Perl itself.