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.06
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       auto_error_container_class
339
340       Add a class-name to the error container.
341
342       Supports substitutions: %f, %n.
343
344       Is an inheriting accessor.
345
346       auto_error_container_per_error_class
347
348       Add a class-name to the error container for each error on that field.
349
350       Supports substitutions: %f, %n, %t, %s.
351
352       Is an inheriting accessor.
353
354   ERROR MESSAGES
355       error_tag
356
357       Default value: 'span'
358
359       Sets the tag used to wrap each individual error message.
360
361       Defaults to "span".
362
363       Is an inheriting accessor.
364
365       auto_error_message
366
367       Default Value: 'form_%s_%t'
368
369       If set, then each error will be given an auto-generated message, if it
370       doesn't have one already.
371
372       The generated string will be passed to "localize" to create the
373       message.
374
375       For example, a Required constraint will return the string
376       "form_constraint_required". Under the default localization behaviour,
377       the appropriate message for "form_constraint_required" will be used
378       from the default I18N package.
379
380       Supports substitutions: %f, %n, %t, %s.
381
382       Is an inheriting accessor.
383
384       error_attributes
385
386       Set attributes on the tag of each error message.
387
388       Is an attribute accessor.
389
390       auto_error_field_class
391
392       Upon error, add a class name firectly to the field tag (e.g. "input",
393       "select" tag).
394
395       Supports substitutions: %f, %n.
396
397       auto_error_class
398
399       Default Value: 'error_%s_%t'
400
401       Add a class-name to the tag of each error message.
402
403       Supports substitutions: %f, %n, %t, %s.
404
405       Is an inheriting accessor.
406
407   PROCESSOR CLASSES
408       auto_constraint_class
409
410       Add a class-name to the container tag, for each constraint added to the
411       field.
412
413       Supports substitutions: %f, %n, %t.
414
415       Is an inheriting accessor.
416
417       auto_inflator_class
418
419       Add a class-name to the container tag, for each inflator added to the
420       field.
421
422       Supports substitutions: %f, %n, %t.
423
424       Is an inheriting accessor.
425
426       auto_validator_class
427
428       Add a class-name to the container tag, for each validator added to the
429       field.
430
431       Supports substitutions: %f, %n, %t.
432
433       Is an inheriting accessor.
434
435       auto_transformer_class
436
437       Add a class-name to the container tag, for each transformer added to
438       the field.
439
440       Supports substitutions: %f, %n, %t.
441
442       Is an inheriting accessor.
443
444   REORDERING FIELD COMPONENTS
445   layout
446       Specify the order that each sub-part of the element should appear in
447       the rendered markup.
448
449           # Default Value
450           $element->layout( [
451               'errors',
452               'label',
453               'field',
454               'comment',
455               'javascript',
456           ] );
457
458       Example: Move the form field (the input tag or equivalent) inside the
459       label tag, after the label text.  Remove the comment - this will now
460       never be rendered.
461
462           # YAML config
463           layout:
464             - errors
465             - label:
466                 - label_text
467                 - field
468             - javascript
469
470           # prettified example of rendered markup
471           <div>
472               <span>This field is required.</span>
473               <label>
474                   Foo
475                   <input name="foo" type="text" />
476               </label>
477           </div>
478
479       Example: Don't wrap the label text inside it's usual tag.  Insert the
480       form field (the input tag or equivalent) inside an arbitrary extra tag.
481
482           # YAML config
483           layout:
484             - errors
485             - label_text
486             -
487               div:
488                 attributes:
489                   class: xxx
490                 content: field
491             - comment
492             - javascript
493
494           # prettified example of rendered markup
495           <div>
496               <span>This field is required.</span>
497               Foo
498               <div class="xxx">
499                   <input name="foo" type="text" />
500               </div>
501           </div>
502
503       The following elements override the default layout value:
504
505       HTML::FormFu::Element::Checkboxgroup
506       HTML::FormFu::Element::Hidden
507
508       Specification
509
510       The layout method accepts an array-ref, hash-ref, or string argument.
511
512       The processing is recursive, so each item in an array-ref may be any
513       value accepted by the layout method.
514
515       A hash-ref must contain a single key and value pair.  If the hash key
516       is the string "label", it creates a "label" tag, using any previously
517       defined LABEL customizations.  This allows the label tag to contains
518       other elements, such as the form field.
519
520       All other hash key values are asssumed to be an arbitrary block tag
521       name.  The value must be a hash-ref, and may contain one or both
522       "attributes" or "content" keys.
523
524       Any "attributes" value must be a hash-ref, whose key/values are added
525       to the block tag. No processing or expansion is done to the
526       "attributes" hash-ref at all.
527
528       The "content" value may be anything accepted by the layout method.
529
530       The following strings are accepted:
531
532       errors
533           Renders the element error messages.
534
535           See ERROR CONTAINER and ERROR MESSAGES to customize the tags and
536           attributes.
537
538       label
539           Renders the element label.
540
541           See LABEL to customize the tag and attributes.
542
543       label_text
544           Renders the element label text, without the usual label_tag.
545
546       field
547           Renders the form field control (an input tag, button, or other
548           control).
549
550       comment
551           Renders the element comment.
552
553           See COMMENT to customize the tag and attributes.
554
555       javascript
556           Renders a "script" tag containing any javascript.
557
558   multi_layout
559       Specify the order that each sub-part of each element within a
560       HTML::FormFu::Element::Multi should appear in the rendered markup.
561
562           # Default Value
563           $element->multi_layout( [
564               'label',
565               'field',
566           ] );
567
568       Example: Swap the label/field order. This is equivalent to the now-
569       deprecated reverse_multi method.
570
571           # YAML config
572           multi_layout:
573             - field
574             - label
575
576       The following elements override the default "multi_layout" value:
577
578       HTML::FormFu::Element::Checkbox
579

RENDERING

581   field_filename
582       The template filename to be used for just the form field - not
583       including the display of any container, label, errors, etc.
584
585       Must be set by more specific field classes.
586
587   label_filename
588       The template filename to be used to render the label.
589
590       Defaults to "label".
591

ERROR HANDLING

593   get_errors
594       See "get_errors" in HTML::FormFu for details.
595
596   add_error
597   clear_errors
598       See "clear_errors" in HTML::FormFu for details.
599

INTROSPECTION

601   get_deflators
602       See "get_deflators" in HTML::FormFu for details.
603
604   get_deflator
605       See "get_deflator" in HTML::FormFu for details.
606
607   get_filters
608       See "get_filters" in HTML::FormFu for details.
609
610   get_filter
611       See "get_filter" in HTML::FormFu for details.
612
613   get_constraints
614       See "get_constraints" in HTML::FormFu for details.
615
616   get_constraint
617       See "get_constraint" in HTML::FormFu for details.
618
619   get_inflators
620       See "get_inflators" in HTML::FormFu for details.
621
622   get_inflator
623       See "get_inflator" in HTML::FormFu for details.
624
625   get_validators
626       See "get_validators" in HTML::FormFu for details.
627
628   get_validator
629       See "get_validator" in HTML::FormFu for details.
630
631   get_transformers
632       See "get_transformers" in HTML::FormFu for details.
633
634   get_transformer
635       See "get_transformer" in HTML::FormFu for details.
636
637   get_errors
638       See "get_errors" in HTML::FormFu for details.
639
640   clear_errors
641       See "clear_errors" in HTML::FormFu for details.
642

DEPRECATED METHODS

644       reverse_single
645           See layout instead.
646
647       reverse_multi
648           See multi_layout instead.
649
650       errors_filename
651           See layout_errors_filename instead.
652

AUTHOR

663       Carl Franks, "cfranks@cpan.org"
664

LICENSE

666       This library is free software, you can redistribute it and/or modify it
667       under the same terms as Perl itself.
668

AUTHOR

670       Carl Franks <cpan@fireartist.com>
671

COPYRIGHT AND LICENSE

673       This software is copyright (c) 2018 by Carl Franks.
674
675       This is free software; you can redistribute it and/or modify it under
676       the same terms as the Perl 5 programming language system itself.
677
678
679
680perl v5.28.0                      2018-04-H0T9ML::FormFu::Role::Element::Field(3)