Provided by: libhtml-formfu-perl_2.05000-1_all 
NAME
HTML::FormFu::Role::Element::Field - Role for all form-field elements
VERSION
version 2.05
DESCRIPTION
Base-class for all form-field elements.
METHODS
default
Set the form-field's default value.
Is an output accessor.
value
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.
Is an output accessor.
non_param
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
placeholder
Sets the HTML5 attribute "placeholder" to the specified value.
Is an output accessor.
javascript
Arguments: [$javascript]
If set, the contents will be rendered within a "script" tag, within the field's container.
retain_default
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.
Default Value: "false"
force_default
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.
Default Value: "false"
default_empty_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 Value: "false"
repeatable_count
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.
clone
See "clone" in HTML::FormFu for details.
deflators
See "deflators" in HTML::FormFu for details.
deflator
See "deflator" in HTML::FormFu for details.
auto_datalist_id
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.
Is an inheriting accessor.
FORM LOGIC AND VALIDATION
filters
See "filters" in HTML::FormFu for details.
filter
See "filter" in HTML::FormFu for details.
constraints
See "constraints" in HTML::FormFu for details.
constraint
See "constraint" in HTML::FormFu for details.
inflators
See "inflators" in HTML::FormFu for details.
inflator
See "inflator" in HTML::FormFu for details.
validators
See "validators" in HTML::FormFu for details.
validator
See "validator" in HTML::FormFu for details.
transformers
See "transformers" in HTML::FormFu for details.
transformer
See "transformer" in HTML::FormFu for details.
CUSTOMIZING GENERATED MARKUP
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.
CONTAINER
container_tag
Default value: 'div'
The container wrapping each entire field, any label, comment, and errors.
container_attributes
Attributes added to the container tag.
Is an attribute accessor.
auto_container_class
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.
Is an inheriting accessor.
auto_container_label_class
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.
Supports substitutions: %f, %n, %t.
Is an inheriting accessor.
auto_container_comment_class
Default Value: '%t'
If set, and if the field has a comment, the container will be given a class-name based on
the given pattern.
Supports substitutions: %f, %n, %t.
Is an inheriting accessor.
auto_container_error_class
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.
Is an inheriting accessor.
auto_container_per_error_class
Default Value: 'error_%s_%t'
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, %t, %s.
Is an inheriting accessor.
FORM FIELD
auto_id
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.
Supports substitutions: %f, %n, %r.
Is an inheriting accessor.
LABEL
label
Set a label to communicate the purpose of the form-field to the user.
Is an output accessor.
auto_label
If label isn't already set, the value of "auto_label" is passed through localize to
generate a label.
Supports substitutions: %f, %n.
The generated string will be passed to "localize" to create the label.
Is an inheriting accessor.
label_tag
Default value: 'label' (except Checkboxgroup)
Default value: 'legend' (only Checkboxgroup)
Set which tag is used to wrap a label.
Is an inheriting accessor.
label_attributes
Attributes added to the label container.
Is an attribute accessor.
COMMENT
comment
Set a comment to be displayed along with the form-field.
Is an output accessor.
comment_attributes
Attributes added to the comment container.
Is an attribute accessor.
auto_comment_class
Default Value: '%t'
If set, and if the field has a comment, the comment tag will be given a class-name based
on the given pattern.
Supports substitutions: %f, %n, %t.
Is an inheriting accessor.
ERROR CONTAINER
error_container_tag
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
Is an inheriting accessor.
auto_error_container_class
Add a class-name to the error container.
Supports substitutions: %f, %n.
Is an inheriting accessor.
auto_error_container_per_error_class
Add a class-name to the error container for each error on that field.
Supports substitutions: %f, %n, %t, %s.
Is an inheriting accessor.
ERROR MESSAGES
error_tag
Default value: 'span'
Sets the tag used to wrap each individual error message.
Defaults to "span".
Is an inheriting accessor.
auto_error_message
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.
Supports substitutions: %f, %n, %t, %s.
Is an inheriting accessor.
error_attributes
Set attributes on the tag of each error message.
Is an attribute accessor.
auto_error_class
Default Value: 'error_%s_%t'
Add a class-name to the tag of each error message.
Supports substitutions: %f, %n, %t, %s.
Is an inheriting accessor.
PROCESSOR CLASSES
auto_constraint_class
Add a class-name to the container tag, for each constraint added to the field.
Supports substitutions: %f, %n, %t.
Is an inheriting accessor.
auto_inflator_class
Add a class-name to the container tag, for each inflator added to the field.
Supports substitutions: %f, %n, %t.
Is an inheriting accessor.
auto_validator_class
Add a class-name to the container tag, for each validator added to the field.
Supports substitutions: %f, %n, %t.
Is an inheriting accessor.
auto_transformer_class
Add a class-name to the container tag, for each transformer added to the field.
Supports substitutions: %f, %n, %t.
Is an inheriting accessor.
REORDERING FIELD COMPONENTS
layout
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:
HTML::FormFu::Element::Checkboxgroup
HTML::FormFu::Element::Hidden
Specification
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.
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.
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:
errors
Renders the element error messages.
See ERROR CONTAINER and ERROR MESSAGES to customize the tags and attributes.
label
Renders the element label.
See LABEL to customize the tag and attributes.
label_text
Renders the element label text, without the usual label_tag.
field
Renders the form field control (an input tag, button, or other control).
comment
Renders the element comment.
See COMMENT to customize the tag and attributes.
javascript
Renders a "script" tag containing any javascript.
multi_layout
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:
HTML::FormFu::Element::Checkbox
RENDERING
field_filename
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.
label_filename
The template filename to be used to render the label.
Defaults to "label".
ERROR HANDLING
get_errors
See "get_errors" in HTML::FormFu for details.
add_error
clear_errors
See "clear_errors" in HTML::FormFu for details.
INTROSPECTION
get_deflators
See "get_deflators" in HTML::FormFu for details.
get_deflator
See "get_deflator" in HTML::FormFu for details.
get_filters
See "get_filters" in HTML::FormFu for details.
get_filter
See "get_filter" in HTML::FormFu for details.
get_constraints
See "get_constraints" in HTML::FormFu for details.
get_constraint
See "get_constraint" in HTML::FormFu for details.
get_inflators
See "get_inflators" in HTML::FormFu for details.
get_inflator
See "get_inflator" in HTML::FormFu for details.
get_validators
See "get_validators" in HTML::FormFu for details.
get_validator
See "get_validator" in HTML::FormFu for details.
get_transformers
See "get_transformers" in HTML::FormFu for details.
get_transformer
See "get_transformer" in HTML::FormFu for details.
get_errors
See "get_errors" in HTML::FormFu for details.
clear_errors
See "clear_errors" in HTML::FormFu for details.
DEPRECATED METHODS
reverse_single
See layout instead.
reverse_multi
See multi_layout instead.
errors_filename
See layout_errors_filename instead.
SEE ALSO
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
AUTHOR
Carl Franks, "cfranks@cpan.org"
LICENSE
This library is free software, you can redistribute it and/or modify it under the same
terms as Perl itself.