HTML::FormFu::Role::Element::Field - Role for all form-field elements
version 2.07
Base-class for all form-field elements.
Set the form-field's default value.
Is an output accessor.
For most fields, "value" is an alias for "default".
For the HTML::FormFu::Element::Checkbox and HTML::FormFu::Element::Radio elements, "value" sets what the value of the field will be if it is checked or selected. If the "default" is the same as the "value", then the field will be checked or selected when rendered.
For the HTML::FormFu::Element::Radiogroup and HTML::FormFu::Element::Select elements, the "value" is ignored: values or options provides the equivalent function.
Arguments: bool
Default Value: false
If true, values for this field are never returned by "params" in HTML::FormFu, "param" in HTML::FormFu and "valid" in HTML::FormFu.
This is useful for Submit buttons, when you only use its value as an indicator
Sets the HTML5 attribute placeholder to the specified value.
placeholder
Arguments: [$javascript]
If set, the contents will be rendered within a script tag, within the field's container.
script
If "retain_default" is true and the form was submitted, but the field didn't have a value submitted, then when the form is redisplayed to the user the field will have its value set to its default value, rather than the usual behaviour of having an empty value.
false
If "force_default" is true and the form was submitted, and the field has a default/value set, then when the form is redisplayed to the user the field will have its value set to its default value.
If the default value is being changed after FormFu->process is being called the later default value is respected for rendering, *but* nevertheless the input value doesn't respect that, it will remain the first value.
Designed for use by Checkbox fields. Normally if a checkbox is not checked, no value is submitted for that field. If default_empty_value is true, the Checkbox field is given an empty value during process. Please note that, with this setting, the checkbox gets an EMPTY value (as opposed to no value at all without enabling it), NOT the default value assigned to the element (if any).
default_empty_value
Only available for fields attached to a Repeatable element, after $repeatable->repeat($count) has been called.
The value is inherited from "repeatable_count" in HTML::FormFu::Element::Repeatable.
See "clone" in HTML::FormFu for details.
See "deflators" in HTML::FormFu for details.
See "deflator" in HTML::FormFu for details.
Arguments: [$string]
If any Input element had a datalist, but does not have "datalist_id" in HTML::FormFu::Role::Element::Input set, "auto_datalist_id" is used to generate the datalist id.
The following character substitution will be performed: %f will be replaced by $form->id, %n will be replaced by $field->name, %r will be replaced by $block->repeatable_count.
%f
%n
%r
Is an inheriting accessor.
See "filters" in HTML::FormFu for details.
See "filter" in HTML::FormFu for details.
See "constraints" in HTML::FormFu for details.
See "constraint" in HTML::FormFu for details.
See "inflators" in HTML::FormFu for details.
See "inflator" in HTML::FormFu for details.
See "validators" in HTML::FormFu for details.
See "validator" in HTML::FormFu for details.
See "transformers" in HTML::FormFu for details.
See "transformer" in HTML::FormFu for details.
Each field is, by default, wrapped in a container. Each container may also contain a label, a comment, and after an invalid submission may contain 1 or more error messages.
Example of generated form:
1 <form action="" method="post"> 2 <div class="has-errors"> # container 3 <ul class="errors"> # error container 4 <li> # error message 5 This field must contain an email address 6 </li> 7 </li> 8 <label>Foo</label> # label 9 <input name="foo" type="text" value="example.com" /> 10 <span class="comment"> # comment 11 This is Foo 12 </span> 13 </div> 14 </form> # Line 2 starts the 'container' - by default a DIV. # Line 2 starts an error container, which may contain 1 or more error messages - in this case, a unordered list (UL). # Line 4 starts a single error message - in this case, a list item (LI). # Line 8 shows a 'label'. # Line 9 shows the field's 'input' tag. # Lines 10 starts a 'comment'.
To re-order the various parts of each form (label, input, errors, etc) and arbitrary extra tags, see the layout method.
Default value: 'div'
The container wrapping each entire field, any label, comment, and errors.
Attributes added to the container tag.
Is an attribute accessor.
Default Value: '%t'
If set, then the container of each field will be given a class-name based on the given pattern.
Supports substitutions: %f, %n, %t.
%t
Default Value: 'label'
If set, and if the field has a label, the container will be given a class-name based on the given pattern.
If set, and if the field has a comment, the container will be given a class-name based on the given pattern.
Default Value: 'error'
If set, then the container of each field with an error will be given a class-name based on the given pattern.
Supports substitutions: %f, %n.
Default Value: 'error_%s_%t'
Supports substitutions: %f, %n, %t, %s.
%s
If set, then the field will be given an id attribute, if it doesn't have one already.
E.g., setting $form->auto_id('%n') will make each field have an ID the same as the field's name. This makes our form config simpler, and ensures we don't need to manually update IDs if any field names are changed.
$form->auto_id('%n')
Supports substitutions: %f, %n, %r.
Set a label to communicate the purpose of the form-field to the user.
If label isn't already set, the value of "auto_label" is passed through localize to generate a label.
The generated string will be passed to "localize" to create the label.
Default value: 'label' (except Checkboxgroup)
Default value: 'legend' (only Checkboxgroup)
Set which tag is used to wrap a label.
Attributes added to the label container.
Set a comment to be displayed along with the form-field.
Attributes added to the comment container.
If set, and if the field has a comment, the comment tag will be given a class-name based on the given pattern.
If set, and if the field has any errors, a container of this type is wrapped around all of the field error messages.
# Example - this would wrap each individual error in a 'li' tag, # with a single 'ul' tag wrapped around all the errors. element: name: foo error_container_tag: ul error_tag: li
Set attributes on the container-tag, if "error_container_tag" is set.
Add a class-name to the error container.
Add a class-name to the error container for each error on that field.
Default value: 'span'
Sets the tag used to wrap each individual error message.
Defaults to span.
span
Default Value: 'form_%s_%t'
If set, then each error will be given an auto-generated message, if it doesn't have one already.
The generated string will be passed to "localize" to create the message.
For example, a Required constraint will return the string form_constraint_required. Under the default localization behaviour, the appropriate message for form_constraint_required will be used from the default I18N package.
form_constraint_required
Set attributes on the tag of each error message.
Upon error, add a class name firectly to the field tag (e.g. input, select tag).
input
select
Add a class-name to the tag of each error message.
Add a class-name to the container tag, for each constraint added to the field.
Add a class-name to the container tag, for each inflator added to the field.
Add a class-name to the container tag, for each validator added to the field.
Add a class-name to the container tag, for each transformer added to the field.
Specify the order that each sub-part of the element should appear in the rendered markup.
# Default Value $element->layout( [ 'errors', 'label', 'field', 'comment', 'javascript', ] );
Example: Move the form field (the input tag or equivalent) inside the label tag, after the label text. Remove the comment - this will now never be rendered.
# YAML config layout: - errors - label: - label_text - field - javascript # prettified example of rendered markup <div> <span>This field is required.</span> <label> Foo <input name="foo" type="text" /> </label> </div>
Example: Don't wrap the label text inside it's usual tag. Insert the form field (the input tag or equivalent) inside an arbitrary extra tag.
# YAML config layout: - errors - label_text - div: attributes: class: xxx content: field - comment - javascript # prettified example of rendered markup <div> <span>This field is required.</span> Foo <div class="xxx"> <input name="foo" type="text" /> </div> </div>
The following elements override the default layout value:
The layout method accepts an array-ref, hash-ref, or string argument.
The processing is recursive, so each item in an array-ref may be any value accepted by the layout method.
A hash-ref must contain a single key and value pair. If the hash key is the string label, it creates a label tag, using any previously defined LABEL customizations. This allows the label tag to contains other elements, such as the form field.
label
All other hash key values are asssumed to be an arbitrary block tag name. The value must be a hash-ref, and may contain one or both attributes or content keys.
attributes
content
Any attributes value must be a hash-ref, whose key/values are added to the block tag. No processing or expansion is done to the attributes hash-ref at all.
The content value may be anything accepted by the layout method.
The following strings are accepted:
Renders the element error messages.
See ERROR CONTAINER and ERROR MESSAGES to customize the tags and attributes.
Renders the element label.
See LABEL to customize the tag and attributes.
Renders the element label text, without the usual label_tag.
Renders the form field control (an input tag, button, or other control).
Renders the element comment.
See COMMENT to customize the tag and attributes.
Renders a script tag containing any javascript.
Specify the order that each sub-part of each element within a HTML::FormFu::Element::Multi should appear in the rendered markup.
# Default Value $element->multi_layout( [ 'label', 'field', ] );
Example: Swap the label/field order. This is equivalent to the now-deprecated reverse_multi method.
# YAML config multi_layout: - field - label
The following elements override the default multi_layout value:
multi_layout
The template filename to be used for just the form field - not including the display of any container, label, errors, etc.
Must be set by more specific field classes.
The template filename to be used to render the label.
Defaults to label.
See "get_errors" in HTML::FormFu for details.
See "clear_errors" in HTML::FormFu for details.
See "get_deflators" in HTML::FormFu for details.
See "get_deflator" in HTML::FormFu for details.
See "get_filters" in HTML::FormFu for details.
See "get_filter" in HTML::FormFu for details.
See "get_constraints" in HTML::FormFu for details.
See "get_constraint" in HTML::FormFu for details.
See "get_inflators" in HTML::FormFu for details.
See "get_inflator" in HTML::FormFu for details.
See "get_validators" in HTML::FormFu for details.
See "get_validator" in HTML::FormFu for details.
See "get_transformers" in HTML::FormFu for details.
See "get_transformer" in HTML::FormFu for details.
See layout instead.
See multi_layout instead.
See layout_errors_filename instead.
Base-class for HTML::FormFu::Role::Element::Group, HTML::FormFu::Role::Element::Input, HTML::FormFu::Element::Multi, HTML::FormFu::Element::ContentButton, HTML::FormFu::Element::Textarea.
Is a sub-class of, and inherits methods from HTML::FormFu::Element
HTML::FormFu
Carl Franks, cfranks@cpan.org
cfranks@cpan.org
This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.
Carl Franks <cpan@fireartist.com>
This software is copyright (c) 2018 by Carl Franks.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install HTML::FormFu, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTML::FormFu
CPAN shell
perl -MCPAN -e shell install HTML::FormFu
For more information on module installation, please visit the detailed CPAN module installation guide.