1HTML::FormFu::Element::URseepreaCtoanbtlrei(b3u)ted PerlHTDMoLc:u:mFeonrtmaFtui:o:nElement::Repeatable(3)
2
3
4

NAME

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

VERSION

9       version 2.07
10

SYNOPSIS

12           ---
13           elements:
14             - type: Repeatable
15               name: my_rep
16               elements:
17                 - name: foo
18                 - name: bar
19
20       Calling "$element->repeat(2)" would result in the following markup:
21
22           <div>
23               <input name="my_rep.foo_1" type="text" />
24               <input name="my_rep.bar_1" type="text" />
25           </div>
26           <div>
27               <input name="my_rep.foo_2" type="text" />
28               <input name="my_rep.bar_2" type="text" />
29           </div>
30
31       Example of constraints:
32
33           ----
34           elements:
35             - type: Repeatable
36               name: my_rep
37               elements:
38                 - name: id
39
40                 - name: foo
41                   constraints:
42                     - type: Required
43                       when:
44                         field: 'my_rep.id' # use full nested-name
45
46                 - name: bar
47                   constraints:
48                     - type: Equal
49                       others: 'my_rep.foo' # use full nested-name
50

DESCRIPTION

52       Provides a way to extend a form at run-time, by copying and repeating
53       its child elements.
54
55       The elements intended for copying must be added before "repeat" is
56       called.
57
58       Although the Repeatable element inherits from Block, it doesn't
59       generate a block tag around all the repeated elements - instead it
60       places each repeat of the elements in a new Block element, which
61       inherits the Repeatable's display settings, such as "attributes" and
62       "tag".
63
64       For all constraints attached to fields within a Repeatable block which
65       use either others or when containing names of fields within the same
66       Repeatable block, when repeat is called, those names will automatically
67       be updated to the new nested-name for each field (taking into account
68       increment_field_names).
69

METHODS

71   repeat
72       Arguments: [$count]
73
74       Return Value: $arrayref_of_new_child_blocks
75
76       This method creates $count number of copies of the child elements.  If
77       no argument $count is provided, it defaults to 1.
78
79       Note that "$form->process" will call "repeat" automatically to ensure
80       the initial child elements are correctly set up - unless you call
81       "repeat" manually first, in which case the child elements you created
82       will be left untouched (otherwise process would overwrite your
83       changes).
84
85       Any subsequent call to "repeat" will delete the previously copied
86       elements before creating new copies - this means you cannot make
87       repeated calls to "repeat" within a loop to create more copies.
88
89       Each copy of the elements returned are contained in a new Block
90       element. For example, calling "$element->repeat(2)" on a Repeatable
91       element containing 2 Text fields would return 2 Block elements, each
92       containing a copy of the 2 Text fields.
93
94   counter_name
95       Arguments: $name
96
97       If true, the "query" in HTML::FormFu will be searched during "process"
98       in HTML::FormFu for a parameter with the given name. The value for that
99       parameter will be passed to "repeat", to automatically create the new
100       copies.
101
102       If "increment_field_names" is true (the default), this is essential: if
103       the elements corresponding to the new fieldnames (foo_1, bar_2, etc.)
104       are not present on the form during "process" in HTML::FormFu, no
105       Processors (Constraints, etc.) will be run on the fields, and their
106       values will not be returned by "params" in HTML::FormFu or "param" in
107       HTML::FormFu.
108
109   increment_field_names
110       Arguments: $bool
111
112       Default Value: 1
113
114       If true, then all fields will have "_n" appended to their name, where
115       "n" is the "repeatable_count" value.
116
117   repeatable_count
118       This is set on each new Block element returned by "repeat", starting at
119       number 1.
120
121       Because this is an 'inherited accessor' available on all elements, it
122       can be used to determine whether any element is a child of a Repeatable
123       element.
124
125       Only available after repeat has been called.
126
127   repeatable_count_no_inherit
128       A non-inheriting variant of "repeatable_count".
129
130   nested_name
131       If the "nested_name" attribute is set, the naming scheme of the
132       Repeatable element's children is switched to add the counter to the
133       repeatable blocks themselves.
134
135           ---
136           elements:
137             - type: Repeatable
138               nested_name: my_rep
139               elements:
140                 - name: foo
141                 - name: bar
142
143       Calling "$element->repeat(2)" would result in the following markup:
144
145           <div>
146               <input name="my_rep_1.foo" type="text" />
147               <input name="my_rep_1.bar" type="text" />
148           </div>
149           <div>
150               <input name="my_rep_2.foo" type="text" />
151               <input name="my_rep_2.bar" type="text" />
152           </div>
153
154       Because this is an 'inherited accessor' available on all elements, it
155       can be used to determine whether any element is a child of a Repeatable
156       element.
157
158   attributes
159   attrs
160       Any attributes set will be passed to every repeated Block of elements.
161
162           ---
163           elements:
164             - type: Repeatable
165               name: my_rep
166               attributes:
167                 class: rep
168               elements:
169                 - name: foo
170
171       Calling "$element->repeat(2)" would result in the following markup:
172
173           <div class="rep">
174               <input name="my_rep.foo_1" type="text" />
175           </div>
176           <div class="rep">
177               <input name="my_rep.foo_2" type="text" />
178           </div>
179
180       See "attributes" in HTML::FormFu for details.
181
182   tag
183       The "tag" value will be passed to every repeated Block of elements.
184
185           ---
186           elements:
187             - type: Repeatable
188               name: my_rep
189               tag: span
190               elements:
191                 - name: foo
192
193       Calling "$element->repeat(2)" would result in the following markup:
194
195           <span>
196               <input name="my_rep.foo_1" type="text" />
197           </span>
198           <span>
199               <input name="my_rep.foo_2" type="text" />
200           </span>
201
202       See "tag" in HTML::FormFu::Element::Block for details.
203
204   auto_id
205       As well as the usual substitutions, any instances of %r will be
206       replaced with the value of "repeatable_count".
207
208       See "auto_id" in HTML::FormFu::Element::Block for further details.
209
210           ---
211           elements:
212             - type: Repeatable
213               name: my_rep
214               auto_id: "%n_%r"
215               elements:
216                 - name: foo
217
218       Calling "$element->repeat(2)" would result in the following markup:
219
220           <div>
221               <input name="my_rep.foo_1" id="foo_1" type="text" />
222           </div>
223           <div>
224               <input name="my_rep.foo_2" id="foo_2" type="text" />
225           </div>
226
227   content
228       Not supported for Repeatable elements - will throw a fatal error if
229       called as a setter.
230

CAVEATS

232   Unsupported Constraints
233       Note that constraints with an others method do not work correctly
234       within a Repeatable block. Currently, these are: AllOrNone, DependOn,
235       Equal, MinMaxFields, reCAPTCHA.  Also, the CallbackOnce constraint
236       won't work within a Repeatable block, as it wouldn't make much sense.
237
238   Work-arounds
239       See HTML::FormFu::Filter::ForceListValue to address a problem with
240       increment_field_names disabled, and increading the repeat on the
241       server-side.
242

SEE ALSO

244       Is a sub-class of, and inherits methods from
245       HTML::FormFu::Element::Block, HTML::FormFu::Element
246
247       HTML::FormFu
248

AUTHOR

250       Carl Franks, "cfranks@cpan.org"
251

LICENSE

253       This library is free software, you can redistribute it and/or modify it
254       under the same terms as Perl itself.
255

AUTHOR

257       Carl Franks <cpan@fireartist.com>
258
260       This software is copyright (c) 2018 by Carl Franks.
261
262       This is free software; you can redistribute it and/or modify it under
263       the same terms as the Perl 5 programming language system itself.
264
265
266
267perl v5.34.0                      2022-01-2H1TML::FormFu::Element::Repeatable(3)
Impressum