1HTML::FormFu::Element::URseepreaCtoanbtlrei(b3u)ted PerlHTDMoLc:u:mFeonrtmaFtui:o:nElement::Repeatable(3)
2
6 HTML::FormFu::Element::Repeatable - repeatable block element
7
9 version 2.07
10
12 ---
13 elements:
14 - type: Repeatable
15 name: my_rep
16 elements:
17 - name: foo
18 - name: bar
19 Calling "$element->repeat(2)" would result in the following markup:
21 <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 Example of constraints:
32 ----
34 elements:
35 - type: Repeatable
36 name: my_rep
37 elements:
38 - name: id
39 - name: foo
41 constraints:
42 - type: Required
43 when:
44 field: 'my_rep.id' # use full nested-name
45 - name: bar
47 constraints:
48 - type: Equal
49 others: 'my_rep.foo' # use full nested-name
50
52 Provides a way to extend a form at run-time, by copying and repeating
53 its child elements.
54 The elements intended for copying must be added before "repeat" is
56 called.
57 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 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
71 repeat
72 Arguments: [$count]
73 Return Value: $arrayref_of_new_child_blocks
75 This method creates $count number of copies of the child elements. If
77 no argument $count is provided, it defaults to 1.
78 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 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 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 counter_name
95 Arguments: $name
96 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 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 increment_field_names
110 Arguments: $bool
111 Default Value: 1
113 If true, then all fields will have "_n" appended to their name, where
115 "n" is the "repeatable_count" value.
116 repeatable_count
118 This is set on each new Block element returned by "repeat", starting at
119 number 1.
120 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 Only available after repeat has been called.
126 repeatable_count_no_inherit
128 A non-inheriting variant of "repeatable_count".
129 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 ---
136 elements:
137 - type: Repeatable
138 nested_name: my_rep
139 elements:
140 - name: foo
141 - name: bar
142 Calling "$element->repeat(2)" would result in the following markup:
144 <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 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 attributes
159 attrs
160 Any attributes set will be passed to every repeated Block of elements.
161 ---
163 elements:
164 - type: Repeatable
165 name: my_rep
166 attributes:
167 class: rep
168 elements:
169 - name: foo
170 Calling "$element->repeat(2)" would result in the following markup:
172 <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 See "attributes" in HTML::FormFu for details.
181 tag
183 The "tag" value will be passed to every repeated Block of elements.
184 ---
186 elements:
187 - type: Repeatable
188 name: my_rep
189 tag: span
190 elements:
191 - name: foo
192 Calling "$element->repeat(2)" would result in the following markup:
194 <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 See "tag" in HTML::FormFu::Element::Block for details.
203 auto_id
205 As well as the usual substitutions, any instances of %r will be
206 replaced with the value of "repeatable_count".
207 See "auto_id" in HTML::FormFu::Element::Block for further details.
209 ---
211 elements:
212 - type: Repeatable
213 name: my_rep
214 auto_id: "%n_%r"
215 elements:
216 - name: foo
217 Calling "$element->repeat(2)" would result in the following markup:
219 <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 content
228 Not supported for Repeatable elements - will throw a fatal error if
229 called as a setter.
230
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 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
244 Is a sub-class of, and inherits methods from
245 HTML::FormFu::Element::Block, HTML::FormFu::Element
246 HTML::FormFu
248
250 Carl Franks, "cfranks@cpan.org"
251
253 This library is free software, you can redistribute it and/or modify it
254 under the same terms as Perl itself.
255
257 Carl Franks <cpan@fireartist.com>
258
260 This software is copyright (c) 2018 by Carl Franks.
261 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.
264perl v5.34.0 2021-07-2H2TML::FormFu::Element::Repeatable(3)