.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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 >0, 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "HTML::FormHandler::Field::Repeatable 3pm"
.TH HTML::FormHandler::Field::Repeatable 3pm "2017-11-11" "perl v5.26.1" "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::FormHandler::Field::Repeatable \- repeatable (array) field
.SH "VERSION"
.IX Header "VERSION"
version 0.40068
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
In a form, for an array of hashrefs, equivalent to a 'has_many' database
relationship.
.PP
.Vb 5
\&  has_field \*(Aqaddresses\*(Aq => ( type => \*(AqRepeatable\*(Aq );
\&  has_field \*(Aqaddresses.address_id\*(Aq => ( type => \*(AqPrimaryKey\*(Aq );
\&  has_field \*(Aqaddresses.street\*(Aq;
\&  has_field \*(Aqaddresses.city\*(Aq;
\&  has_field \*(Aqaddresses.state\*(Aq;
.Ve
.PP
In a form, for an array of single fields (not directly equivalent to a
database relationship) use the 'contains' pseudo field name:
.PP
.Vb 5
\&  has_field \*(Aqtags\*(Aq => ( type => \*(AqRepeatable\*(Aq );
\&  has_field \*(Aqtags.contains\*(Aq => ( type => \*(AqText\*(Aq,
\&       apply => [ { check => [\*(Aqperl\*(Aq, \*(Aqprogramming\*(Aq, \*(Aqlinux\*(Aq, \*(Aqinternet\*(Aq],
\&                    message => \*(AqNot a valid tag\*(Aq } ]
\&  );
.Ve
.PP
or use 'contains' with single fields which are compound fields:
.PP
.Vb 2
\&  has_field \*(Aqaddresses\*(Aq => ( type => \*(AqRepeatable\*(Aq );
\&  has_field \*(Aqaddresses.contains\*(Aq => ( type => \*(Aq+MyAddress\*(Aq );
.Ve
.PP
If the MyAddress field contains fields 'address_id', 'street', 'city', and
\&'state', then this syntax is functionally equivalent to the first method
where the fields are declared with dots ('addresses.city');
.PP
You can pass attributes to the 'contains' field by supplying an 'init_contains' hashref.
.PP
.Vb 3
\&    has_field \*(Aqaddresses\*(Aq => ( type => \*(AqRepeatable,
\&       init_contains => { wrapper_attr => { class => [\*(Aqhfh\*(Aq, \*(Aqrepinst\*(Aq] } },
\&    );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class represents an array. It can either be an array of hashrefs
(compound fields) or an array of single fields.
.PP
The 'contains' keyword is used for elements that do not have names
because they are not hash elements.
.PP
This field node will build arrays of fields from the parameters or an
initial object, or empty fields for an empty form.
.PP
The name of the element fields will be an array index,
starting with 0. Therefore the first array element can be accessed with:
.PP
.Vb 2
\&   $form\->field(\*(Aqtags\*(Aq)\->field(\*(Aq0\*(Aq)
\&   $form\->field(\*(Aqaddresses\*(Aq)\->field(\*(Aq0\*(Aq)\->field(\*(Aqcity\*(Aq)
.Ve
.PP
or using the shortcut form:
.PP
.Vb 2
\&   $form\->field(\*(Aqtags.0\*(Aq)
\&   $form\->field(\*(Aqaddresses.0.city\*(Aq)
.Ve
.PP
The array of elements will be in \f(CW\*(C`$form\->field(\*(Aqaddresses\*(Aq)\->fields\*(C'\fR.
The subfields of the elements will be in a fields array in each element.
.PP
.Vb 7
\&   foreach my $element ( $form\->field(\*(Aqaddresses\*(Aq)\->fields )
\&   {
\&      foreach my $field ( $element\->fields )
\&      {
\&         # do something
\&      }
\&   }
.Ve
.PP
Every field that has a 'fields' array will also have an 'error_fields' array
containing references to the fields that contain errors.
.SS "Complications"
.IX Subsection "Complications"
When new elements are created by a Repeatable field in a database form
an attempt is made to re-load the Repeatable field from the database, because
otherwise the repeatable elements will not have primary keys. Although this
works, if you have included other fields in your repeatable elements
that do *not* come from the database, the defaults/values must be
able to be loaded in a way that works when the form is initialized from
the database item. This is only an issue if you re-present the form
after the database update succeeds.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.IP "index" 4
.IX Item "index"
This attribute contains the next index number available to create an
additional array element.
.IP "init_contains" 4
.IX Item "init_contains"
When the Repeatable is repeated, this hashref will be used to initialise each
instance. It can contain any of the same attributes you would normally give to
\&\*(L"has_field\*(R" in HTML::FormHandler, except \f(CW\*(C`type\*(C'\fR, for obvious reasons.
.Sp
.Vb 9
\&    has_field \*(Aqaddresses\*(Aq => (
\&        type => \*(AqRepeatable\*(Aq,
\&        init_contains => {
\&            wrapper_attr => {
\&                rel => \*(Aqaddress\*(Aq
\&            },
\&            wrapper_class => [ \*(Aqrow\*(Aq ]
\&        }
\&    );
.Ve
.Sp
Note that providing a \f(CW\*(C`wrapper_class\*(C'\fR to this hashref will override the default
\&\f(CW\*(C`hfh\-repinst\*(C'\fR class on these instances.
.IP "num_when_empty" 4
.IX Item "num_when_empty"
This attribute (default 1) indicates how many empty fields to present
in an empty form which hasn't been filled from parameters or database
rows.
.IP "num_extra" 4
.IX Item "num_extra"
When the field results are built from an existing object (item or init_object)
an additional number of repeatable elements will be created equal to this
number. Default is 0.
.IP "add_extra" 4
.IX Item "add_extra"
When a form is submitted and the field results are built from the input
parameters, it's not clear when or if an additional repeatable element might
be wanted. The method 'add_extra' will add an empty repeatable element.
.Sp
.Vb 2
\&    $form\->process( params => {....} );
\&    $form\->field(\*(Aqmy_repeatable\*(Aq)\->add_extra(1);
.Ve
.Sp
This might be useful if the form is being re-presented to the user.
.IP "setup_for_js" 4
.IX Item "setup_for_js"
.Vb 1
\&    setup_for_js => 1
.Ve
.Sp
Saves information in the form for javascript to use when adding repeatable elements.
If using the example javascript, you also must set 'do_wrapper' in the
Repeatable field and use the Bootstrap widget wrapper (or wrap the repeatable
elements in a 'controls' div by setting tags => { controls_div => 1 }.
See t/repeatable/js.t for an example. See also
HTML::FormHandler::Render::RepeatableJs and HTML::FormHandler::Field::AddElement.
.SH "AUTHOR"
.IX Header "AUTHOR"
FormHandler Contributors \- see HTML::FormHandler
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2017 by Gerda Shank.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.