1HTML::FormFu::Role::EleUmseenrt:C:oFniterlidb(u3t)ed PerHlTMDLo:c:uFmoernmtFaut:i:oRnole::Element::Field(3)
2
3
4
6 HTML::FormFu::Role::Element::Field - Role for all form-field elements
7
9 version 2.07
10
12 Base-class for all form-field elements.
13
15 default
16 Set the form-field's default value.
17
18 Is an output accessor.
19
20 value
21 For most fields, "value" is an alias for "default".
22
23 For the HTML::FormFu::Element::Checkbox and
24 HTML::FormFu::Element::Radio elements, "value" sets what the value of
25 the field will be if it is checked or selected. If the "default" is the
26 same as the "value", then the field will be checked or selected when
27 rendered.
28
29 For the HTML::FormFu::Element::Radiogroup and
30 HTML::FormFu::Element::Select elements, the "value" is ignored: values
31 or options provides the equivalent function.
32
33 Is an output accessor.
34
35 non_param
36 Arguments: bool
37
38 Default Value: false
39
40 If true, values for this field are never returned by "params" in
41 HTML::FormFu, "param" in HTML::FormFu and "valid" in HTML::FormFu.
42
43 This is useful for Submit buttons, when you only use its value as an
44 indicator
45
46 placeholder
47 Sets the HTML5 attribute "placeholder" to the specified value.
48
49 Is an output accessor.
50
51 javascript
52 Arguments: [$javascript]
53
54 If set, the contents will be rendered within a "script" tag, within the
55 field's container.
56
57 retain_default
58 If "retain_default" is true and the form was submitted, but the field
59 didn't have a value submitted, then when the form is redisplayed to the
60 user the field will have its value set to its default value, rather
61 than the usual behaviour of having an empty value.
62
63 Default Value: "false"
64
65 force_default
66 If "force_default" is true and the form was submitted, and the field
67 has a default/value set, then when the form is redisplayed to the user
68 the field will have its value set to its default value.
69
70 If the default value is being changed after FormFu->process is being
71 called the later default value is respected for rendering, *but*
72 nevertheless the input value doesn't respect that, it will remain the
73 first value.
74
75 Default Value: "false"
76
77 default_empty_value
78 Designed for use by Checkbox fields. Normally if a checkbox is not
79 checked, no value is submitted for that field. If "default_empty_value"
80 is true, the Checkbox field is given an empty value during process.
81 Please note that, with this setting, the checkbox gets an EMPTY value
82 (as opposed to no value at all without enabling it), NOT the default
83 value assigned to the element (if any).
84
85 Default Value: "false"
86
87 repeatable_count
88 Only available for fields attached to a Repeatable element, after
89 $repeatable->repeat($count) has been called.
90
91 The value is inherited from "repeatable_count" in
92 HTML::FormFu::Element::Repeatable.
93
94 clone
95 See "clone" in HTML::FormFu for details.
96
97 deflators
98 See "deflators" in HTML::FormFu for details.
99
100 deflator
101 See "deflator" in HTML::FormFu for details.
102
103 auto_datalist_id
104 Arguments: [$string]
105
106 If any Input element had a datalist, but does not have "datalist_id" in
107 HTML::FormFu::Role::Element::Input set, "auto_datalist_id" is used to
108 generate the datalist id.
109
110 The following character substitution will be performed: %f will be
111 replaced by $form->id, %n will be replaced by $field->name, %r will be
112 replaced by $block->repeatable_count.
113
114 Is an inheriting accessor.
115
117 filters
118 See "filters" in HTML::FormFu for details.
119
120 filter
121 See "filter" in HTML::FormFu for details.
122
123 constraints
124 See "constraints" in HTML::FormFu for details.
125
126 constraint
127 See "constraint" in HTML::FormFu for details.
128
129 inflators
130 See "inflators" in HTML::FormFu for details.
131
132 inflator
133 See "inflator" in HTML::FormFu for details.
134
135 validators
136 See "validators" in HTML::FormFu for details.
137
138 validator
139 See "validator" in HTML::FormFu for details.
140
141 transformers
142 See "transformers" in HTML::FormFu for details.
143
144 transformer
145 See "transformer" in HTML::FormFu for details.
146
148 Each field is, by default, wrapped in a container. Each container may
149 also contain a label, a comment, and after an invalid submission may
150 contain 1 or more error messages.
151
152 Example of generated form:
153
154 1 <form action="" method="post">
155 2 <div class="has-errors"> # container
156 3 <ul class="errors"> # error container
157 4 <li> # error message
158 5 This field must contain an email address
159 6 </li>
160 7 </li>
161 8 <label>Foo</label> # label
162 9 <input name="foo" type="text" value="example.com" />
163 10 <span class="comment"> # comment
164 11 This is Foo
165 12 </span>
166 13 </div>
167 14 </form>
168
169 # Line 2 starts the 'container' - by default a DIV.
170 # Line 2 starts an error container, which may contain 1 or more error
171 messages - in this case, a unordered list (UL).
172 # Line 4 starts a single error message - in this case, a list item (LI).
173 # Line 8 shows a 'label'.
174 # Line 9 shows the field's 'input' tag.
175 # Lines 10 starts a 'comment'.
176
177 To re-order the various parts of each form (label, input, errors, etc)
178 and arbitrary extra tags, see the layout method.
179
180 CONTAINER
181 container_tag
182
183 Default value: 'div'
184
185 The container wrapping each entire field, any label, comment, and
186 errors.
187
188 container_attributes
189
190 Attributes added to the container tag.
191
192 Is an attribute accessor.
193
194 auto_container_class
195
196 Default Value: '%t'
197
198 If set, then the container of each field will be given a class-name
199 based on the given pattern.
200
201 Supports substitutions: %f, %n, %t.
202
203 Is an inheriting accessor.
204
205 auto_container_label_class
206
207 Default Value: 'label'
208
209 If set, and if the field has a label, the container will be given a
210 class-name based on the given pattern.
211
212 Supports substitutions: %f, %n, %t.
213
214 Is an inheriting accessor.
215
216 auto_container_comment_class
217
218 Default Value: '%t'
219
220 If set, and if the field has a comment, the container will be given a
221 class-name based on the given pattern.
222
223 Supports substitutions: %f, %n, %t.
224
225 Is an inheriting accessor.
226
227 auto_container_error_class
228
229 Default Value: 'error'
230
231 If set, then the container of each field with an error will be given a
232 class-name based on the given pattern.
233
234 Supports substitutions: %f, %n.
235
236 Is an inheriting accessor.
237
238 auto_container_per_error_class
239
240 Default Value: 'error_%s_%t'
241
242 If set, then the container of each field with an error will be given a
243 class-name based on the given pattern.
244
245 Supports substitutions: %f, %n, %t, %s.
246
247 Is an inheriting accessor.
248
249 FORM FIELD
250 auto_id
251
252 If set, then the field will be given an id attribute, if it doesn't
253 have one already.
254
255 E.g., setting "$form->auto_id('%n')" will make each field have an ID
256 the same as the field's name. This makes our form config simpler, and
257 ensures we don't need to manually update IDs if any field names are
258 changed.
259
260 Supports substitutions: %f, %n, %r.
261
262 Is an inheriting accessor.
263
264 LABEL
265 label
266
267 Set a label to communicate the purpose of the form-field to the user.
268
269 Is an output accessor.
270
271 auto_label
272
273 If label isn't already set, the value of "auto_label" is passed through
274 localize to generate a label.
275
276 Supports substitutions: %f, %n.
277
278 The generated string will be passed to "localize" to create the label.
279
280 Is an inheriting accessor.
281
282 label_tag
283
284 Default value: 'label' (except Checkboxgroup)
285
286 Default value: 'legend' (only Checkboxgroup)
287
288 Set which tag is used to wrap a label.
289
290 Is an inheriting accessor.
291
292 label_attributes
293
294 Attributes added to the label container.
295
296 Is an attribute accessor.
297
298 COMMENT
299 comment
300
301 Set a comment to be displayed along with the form-field.
302
303 Is an output accessor.
304
305 comment_attributes
306
307 Attributes added to the comment container.
308
309 Is an attribute accessor.
310
311 auto_comment_class
312
313 Default Value: '%t'
314
315 If set, and if the field has a comment, the comment tag will be given a
316 class-name based on the given pattern.
317
318 Supports substitutions: %f, %n, %t.
319
320 Is an inheriting accessor.
321
322 ERROR CONTAINER
323 error_container_tag
324
325 If set, and if the field has any errors, a container of this type is
326 wrapped around all of the field error messages.
327
328 # Example - this would wrap each individual error in a 'li' tag,
329 # with a single 'ul' tag wrapped around all the errors.
330
331 element:
332 name: foo
333 error_container_tag: ul
334 error_tag: li
335
336 Is an inheriting accessor.
337
338 error_container_attributes
339
340 Set attributes on the container-tag, if "error_container_tag" is set.
341
342 Is an attribute accessor.
343
344 auto_error_container_class
345
346 Add a class-name to the error container.
347
348 Supports substitutions: %f, %n.
349
350 Is an inheriting accessor.
351
352 auto_error_container_per_error_class
353
354 Add a class-name to the error container for each error on that field.
355
356 Supports substitutions: %f, %n, %t, %s.
357
358 Is an inheriting accessor.
359
360 ERROR MESSAGES
361 error_tag
362
363 Default value: 'span'
364
365 Sets the tag used to wrap each individual error message.
366
367 Defaults to "span".
368
369 Is an inheriting accessor.
370
371 auto_error_message
372
373 Default Value: 'form_%s_%t'
374
375 If set, then each error will be given an auto-generated message, if it
376 doesn't have one already.
377
378 The generated string will be passed to "localize" to create the
379 message.
380
381 For example, a Required constraint will return the string
382 "form_constraint_required". Under the default localization behaviour,
383 the appropriate message for "form_constraint_required" will be used
384 from the default I18N package.
385
386 Supports substitutions: %f, %n, %t, %s.
387
388 Is an inheriting accessor.
389
390 error_attributes
391
392 Set attributes on the tag of each error message.
393
394 Is an attribute accessor.
395
396 auto_error_field_class
397
398 Upon error, add a class name firectly to the field tag (e.g. "input",
399 "select" tag).
400
401 Supports substitutions: %f, %n.
402
403 auto_error_class
404
405 Default Value: 'error_%s_%t'
406
407 Add a class-name to the tag of each error message.
408
409 Supports substitutions: %f, %n, %t, %s.
410
411 Is an inheriting accessor.
412
413 PROCESSOR CLASSES
414 auto_constraint_class
415
416 Add a class-name to the container tag, for each constraint added to the
417 field.
418
419 Supports substitutions: %f, %n, %t.
420
421 Is an inheriting accessor.
422
423 auto_inflator_class
424
425 Add a class-name to the container tag, for each inflator added to the
426 field.
427
428 Supports substitutions: %f, %n, %t.
429
430 Is an inheriting accessor.
431
432 auto_validator_class
433
434 Add a class-name to the container tag, for each validator added to the
435 field.
436
437 Supports substitutions: %f, %n, %t.
438
439 Is an inheriting accessor.
440
441 auto_transformer_class
442
443 Add a class-name to the container tag, for each transformer added to
444 the field.
445
446 Supports substitutions: %f, %n, %t.
447
448 Is an inheriting accessor.
449
450 REORDERING FIELD COMPONENTS
451 layout
452 Specify the order that each sub-part of the element should appear in
453 the rendered markup.
454
455 # Default Value
456 $element->layout( [
457 'errors',
458 'label',
459 'field',
460 'comment',
461 'javascript',
462 ] );
463
464 Example: Move the form field (the input tag or equivalent) inside the
465 label tag, after the label text. Remove the comment - this will now
466 never be rendered.
467
468 # YAML config
469 layout:
470 - errors
471 - label:
472 - label_text
473 - field
474 - javascript
475
476 # prettified example of rendered markup
477 <div>
478 <span>This field is required.</span>
479 <label>
480 Foo
481 <input name="foo" type="text" />
482 </label>
483 </div>
484
485 Example: Don't wrap the label text inside it's usual tag. Insert the
486 form field (the input tag or equivalent) inside an arbitrary extra tag.
487
488 # YAML config
489 layout:
490 - errors
491 - label_text
492 -
493 div:
494 attributes:
495 class: xxx
496 content: field
497 - comment
498 - javascript
499
500 # prettified example of rendered markup
501 <div>
502 <span>This field is required.</span>
503 Foo
504 <div class="xxx">
505 <input name="foo" type="text" />
506 </div>
507 </div>
508
509 The following elements override the default layout value:
510
511 HTML::FormFu::Element::Checkboxgroup
512 HTML::FormFu::Element::Hidden
513
514 Specification
515
516 The layout method accepts an array-ref, hash-ref, or string argument.
517
518 The processing is recursive, so each item in an array-ref may be any
519 value accepted by the layout method.
520
521 A hash-ref must contain a single key and value pair. If the hash key
522 is the string "label", it creates a "label" tag, using any previously
523 defined LABEL customizations. This allows the label tag to contains
524 other elements, such as the form field.
525
526 All other hash key values are asssumed to be an arbitrary block tag
527 name. The value must be a hash-ref, and may contain one or both
528 "attributes" or "content" keys.
529
530 Any "attributes" value must be a hash-ref, whose key/values are added
531 to the block tag. No processing or expansion is done to the
532 "attributes" hash-ref at all.
533
534 The "content" value may be anything accepted by the layout method.
535
536 The following strings are accepted:
537
538 errors
539 Renders the element error messages.
540
541 See ERROR CONTAINER and ERROR MESSAGES to customize the tags and
542 attributes.
543
544 label
545 Renders the element label.
546
547 See LABEL to customize the tag and attributes.
548
549 label_text
550 Renders the element label text, without the usual label_tag.
551
552 field
553 Renders the form field control (an input tag, button, or other
554 control).
555
556 comment
557 Renders the element comment.
558
559 See COMMENT to customize the tag and attributes.
560
561 javascript
562 Renders a "script" tag containing any javascript.
563
564 multi_layout
565 Specify the order that each sub-part of each element within a
566 HTML::FormFu::Element::Multi should appear in the rendered markup.
567
568 # Default Value
569 $element->multi_layout( [
570 'label',
571 'field',
572 ] );
573
574 Example: Swap the label/field order. This is equivalent to the now-
575 deprecated reverse_multi method.
576
577 # YAML config
578 multi_layout:
579 - field
580 - label
581
582 The following elements override the default "multi_layout" value:
583
584 HTML::FormFu::Element::Checkbox
585
587 field_filename
588 The template filename to be used for just the form field - not
589 including the display of any container, label, errors, etc.
590
591 Must be set by more specific field classes.
592
593 label_filename
594 The template filename to be used to render the label.
595
596 Defaults to "label".
597
599 get_errors
600 See "get_errors" in HTML::FormFu for details.
601
602 add_error
603 clear_errors
604 See "clear_errors" in HTML::FormFu for details.
605
607 get_deflators
608 See "get_deflators" in HTML::FormFu for details.
609
610 get_deflator
611 See "get_deflator" in HTML::FormFu for details.
612
613 get_filters
614 See "get_filters" in HTML::FormFu for details.
615
616 get_filter
617 See "get_filter" in HTML::FormFu for details.
618
619 get_constraints
620 See "get_constraints" in HTML::FormFu for details.
621
622 get_constraint
623 See "get_constraint" in HTML::FormFu for details.
624
625 get_inflators
626 See "get_inflators" in HTML::FormFu for details.
627
628 get_inflator
629 See "get_inflator" in HTML::FormFu for details.
630
631 get_validators
632 See "get_validators" in HTML::FormFu for details.
633
634 get_validator
635 See "get_validator" in HTML::FormFu for details.
636
637 get_transformers
638 See "get_transformers" in HTML::FormFu for details.
639
640 get_transformer
641 See "get_transformer" in HTML::FormFu for details.
642
643 get_errors
644 See "get_errors" in HTML::FormFu for details.
645
646 clear_errors
647 See "clear_errors" in HTML::FormFu for details.
648
650 reverse_single
651 See layout instead.
652
653 reverse_multi
654 See multi_layout instead.
655
656 errors_filename
657 See layout_errors_filename instead.
658
660 Base-class for HTML::FormFu::Role::Element::Group,
661 HTML::FormFu::Role::Element::Input, HTML::FormFu::Element::Multi,
662 HTML::FormFu::Element::ContentButton, HTML::FormFu::Element::Textarea.
663
664 Is a sub-class of, and inherits methods from HTML::FormFu::Element
665
666 HTML::FormFu
667
669 Carl Franks, "cfranks@cpan.org"
670
672 This library is free software, you can redistribute it and/or modify it
673 under the same terms as Perl itself.
674
676 Carl Franks <cpan@fireartist.com>
677
679 This software is copyright (c) 2018 by Carl Franks.
680
681 This is free software; you can redistribute it and/or modify it under
682 the same terms as the Perl 5 programming language system itself.
683
684
685
686perl v5.36.0 2022-07-H2T2ML::FormFu::Role::Element::Field(3)