Manual Reference Pages - HTML::FORMHANDLER::MANUAL::FIELDS (3)
HTML::FormHandler::Manual::Fields - brief documentation of available fields
See also HTML::FormHandler::Field for a description of the base
The inheritance hierarchy of HTML::FormHandler Fields
A forms fields are created from the has_field and field_list definitions.
FormHandler processes the field lists and creates an array of
HTML::FormHandler::Field objects. The type of a field
determines which field class to use. The field class determines which
attributes are valid for a particular field. A number of field classes are
provided by FormHandler. You can customize the validation in your form on a
per field basis, but validation that will be used for more than one field
might be more easily handled in a custom field class.
Fields are accessed with form->field(name).
Field errors are in $field->errors.
If the field_name_space is not set, fields will be loaded from the
HTML::FormHandler::Field name space. If you provide a field_name_space
it will be searched before FormHandler. If you want to explicitly list the
fields package, prefix it with a plus sign. The field_name_space plus the
default name spaces HTML::FormHandler::Field and HTML::FormHandlerX::Field
will be searched for fields.
has +field_name_space => ( default => MyApp::Form::Field );
has_field name => ( type => Text ); # HTML::FormHandler::Field::Text
has_field name => ( type => +My::FieldType ); # My::Fieldtype
has_field foo => ( type => +Foo ); # MyApp::Form::Field::Foo
has_field foo => ( type => Foo ); # MyApp::Form::Field::Foo
The most basic type is Text, which is usually a text HTML element and
a string data type. (If the type of a field is not specified, it will be set to
Text.) A Select field type is a HTML select element, and validates against
the list of values provided in the options. A Multiple type is like Select
but it allows selecting more than one value at a time.
Many field classes contain only a list of constraints and transformations
to apply. Some use the validate method, which is called after the actions
are applied. Some build a custom select list using build_options.
There are two rough categories of Field classes: those that do extra processing
and those that are simple validators. The Compound, Repeatable, and
Select fields are fields that are functional.
The standard way to use FormHandler is with field names that match your
database accessors. If you want to prepend the HTML field names with a
name plus dot, you can set the form name and use the html_prefix
flag. $name. will be stripped from the beginning of the HTML fields
before processing by HFH, and will be added back in fif. The fields
html_name convenience attribute will return this name for use in templates.
If you want the FormHandler field name to be different than the
database accessor, set accessor on your fields. (It defaults to the field
name.) You could then use any name that you want for your field.
There are a number of name-related field attributes. The name is
the name used to identify this particular field in this fields array.
The full_name includes the names of all parents of this field,
like address.street.streetname. The html_name is the same as the
full_name unless you have set the html_prefix flag, in which case
it includes the form name: myform.address.street.streetname.
To retrieve a field by name, you can use either the full_name or a
Creating custom fields
Subclass a custom field from HTML::FormHandler::Field, or one of the
existing subclasses. Almost everything that is done in a custom field
class can also be done in a form. The advantage of a field class
is that it can simplify declaration of often-repeated sets of attributes.
The simplest subclasses contain only a validate routine or an apply attribute,
which is called by the base Field class from process. Look at
HTML::FormHandler::Field::Email, for example.
If the fields value will be an object instead of a simple scalar, such
as a DateTime, and you want to use the transformed value to fill in the
form, then you will also need a deflation or field class deflate method
to reformat the object into a form suitable for an HTML form field.
See HTML::FormHandler::Manual::InflationDeflation for more info.
Some custom fields might only require setting certain attributes to
defaults, such as the HTML::FormHandler::Field::Hour field, which
set range_start to 0 and range_end to 23. A select field might
override the build_options builder for the options array, like
HTML::FormHandler::Field::IntRange. A field may add additional
attributes, such as label_format in HTML::FormHandler::Field::IntRange,
or set the required message.
An alternative to new field classes for many field validations might
be roles with collections of validations.
Other field packages
Some custom fields are supplied as CPAN packages, in the HTML::FormHandlerX
Fields supplied by FormHandler
Although there are a lot of fields provided (probably too many) a lot of them
are convenience fields or name fields, where the main benefit is
that the field type is a name that gives the main purpose of the field.
Most of these fields could be replaced by a basic field with a bit of validation
or some select options. A few of the fields are special purpose fields
that wont be used very often.
The fields in this section are the basic fields, the commonly used fields
that will be most often used in a form.
A string data type that will be formatted as an HTML text field. Has minlength
and maxlength attributes.
A field formatted as a select element.
A field formatted as a checkbox. If not in params, will be forced to
false value by input_without_param attribute (0 by default).
A hidden field.
A password field. The value is not re-displayed.
A textarea field. Has cols and rows attributes.
A file upload field that takes a filehandle or a Catalyst upload object (an
object with a size method).
A submit field.
A reset field.
Complex Fields (Compound and Repeatable)
These fields are complex fields which contain a fair amount of
special code. They do not map to a single HTML element; they contain
A compound field is a field that has sub-fields. Compound fields can be
created in two ways: 1) using a field class, 2) by declaration.
To create a compound field class, you must extend
HTML::FormHandler::Field::Compound and use HTML::FormHandler::Moose to
allow declaring fields:
has_field month => (type => Integer);
has_field day => ( type => Integer );
has_field minutes => ( type => Integer );
Then in the form:
has_field my_duration => ( type => +Duration );
To create a compound field by declaration, declare the containing
compound field and subfields, prefixing the subfield names
with the name of the containing compound field plus a dot:
has_field duration => ( type => Compound );
has_field duration.month => ( type => Integer );
has_field duration.day => ( type => Integer );
has_field duration.year => ( type => Integer );
In an HTML form the name of the field must be the complete name
with dots. The html_name field attribute can be used to get
this name, $field->html_name.
A compound field can be used for a database relation that will have only
one row (belongs_to or has_one). If the relation has a compound primary
key, you may need to provide the primary key columns, either through
hidden fields or by setting them in the $form->value hash before
update_model is called.
See also HTML::FormHandler::Field::Compound.
Repeatable fields are used for arrays of compound fields.
has_field addresses => ( type => Repeatable );
has_field addresses.address_id => ( type => PrimaryKey );
has_field addresses.country => ( type => Select );
The arrays will be built from arrays passed in the params, or from
related (has_many) rows in the database.
It is also used for arrays of single fields using the contains keyword:
has_field tags => ( type => Repeatable );
has_field tags.contains => ( type => +Tag );
See HTML::FormHandler::Field::Repeatable for more information.
Fields subclassed from the Text field.
Positive or negative real value, formatted to two decimal places.
Date field that can be used by jQuery datepicker plugin.
A subclass of Date with the %m/%d/%Y format.
Uses Email::Valid for validation.
Positive and negative integers. Can use range_start and range_end.
A positive integer field.
Float field that allows you to set size, precision, decimal_symbol, and
A text field that takes multiple values from a database and converts
that require that, such as select2. This is the only multiple text
field. This text field would be a select-type field for the user.
Fields subclassed from Compound.
Compound field with possible subfields: years, months, weeks, days, hours,
minutes, seconds, nanoseconds.
A compound field that requires you to provide the subfields that
you want. (month/day/year/hour/minutes)
Fields that inherit from Checkbox.
Checkbox that return 1 or 0.
Fields that inherit from Select.
Multiple select. Also sorts the selected options to the top of
the select list.
A multiple select field for comma-separated values in the database.
It expects database values like: 1,5,7. The string will be inflated
into an arrayref for validation and form filling, and will be deflated
into a comma-separated string in the output value.
A field with three possible values: empty/0/1.
Integer select range field from 0-23.
Select field with range from 0-59.
An integer select field. Can set label format with label_format.
Select field with range from 1 - 12.
Select field with range from 1 - 31.
Select field with month name labels, value 1-12.
Select field with range from 0-59.
A select field where the labels are the names of the week, and the
values are 0-6.
Select field providing year list 5 years back and 10 years forward.
Fields that inherit from NoValue. None of these fields will
provide a value in the $form->value hashref.
Base class for fields that dont produce a value.
Button field that is rendered by the Button widget.
Non-data field used for inserting HTML into the form. Probably
now better handled by a Block or a rendering tag.
Example field for adding a repeatable element.
Example field for removing a repeatable element
For Bootstrap-style non-editable fields.
Fields that inherit from TextArea.
Password field. Sets noupdate flag if empty and not required.
Password confirmation field.
These fields inherit just from Field.
A file field that does no processing. Most people probably want to
use Upload instead.
Hidden field that provides the primary key for Repeatable fields.
A Captcha field using GD::SecurityImage. Requires the use of the
HTML::FormHandler::TraitFor::Captcha role, or similar code.
FormHandler Contributors - see HTML::FormHandler
COPYRIGHT AND LICENSE
This software is copyright (c) 2016 by Gerda Shank.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
|perl v5.20.3 ||HTML::FORMHANDLER::MANUAL::FIELDS (3) ||2016-03-20 |
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.