HTML::FormFu::Role::Element::Field(3pm)

1HTML::FormFu::Role::EleUmseenrt:C:oFniterlidb(u3t)ed PerHlTMDLo:c:uFmoernmtFaut:i:oRnole::Element::Field(3)
2
3
4

NAME

6       HTML::FormFu::Role::Element::Field - Role for all form-field elements
7

VERSION

9       version 2.07
10

DESCRIPTION

12       Base-class for all form-field elements.
13

METHODS

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

FORM LOGIC AND VALIDATION

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

CUSTOMIZING GENERATED MARKUP

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

RENDERING

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

ERROR HANDLING

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

INTROSPECTION

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

DEPRECATED METHODS

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

AUTHOR

669       Carl Franks, "cfranks@cpan.org"
670

LICENSE

672       This library is free software, you can redistribute it and/or modify it
673       under the same terms as Perl itself.
674

AUTHOR

676       Carl Franks <cpan@fireartist.com>
677

COPYRIGHT AND LICENSE

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                      2023-01-H2T0ML::FormFu::Role::Element::Field(3)