HTML::FormFu::Element::Repeatable(3pm)

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

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

CAVEATS

226   Unsupported Constraints
227       Note that constraints with an others method do not work correctly
228       within a Repeatable block. Currently, these are: AllOrNone, DependOn,
229       Equal, MinMaxFields, reCAPTCHA.  Also, the CallbackOnce constraint
230       won't work within a Repeatable block, as it wouldn't make much sense.
231

AUTHOR

239       Carl Franks, "cfranks@cpan.org"
240

LICENSE

242       This library is free software, you can redistribute it and/or modify it
243       under the same terms as Perl itself.
244
245
246
247perl v5.12.1                      2010-05-2H3TML::FormFu::Element::Repeatable(3)