.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HTML::FormHandler::Manual::Fields 3pm"
.TH HTML::FormHandler::Manual::Fields 3pm "2022-03-25" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTML::FormHandler::Manual::Fields \- brief documentation of available fields
.SH "VERSION"
.IX Header "VERSION"
version 0.40068
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Manual Index
.PP
See also HTML::FormHandler::Field for a description of the base
field attributes.
.PP
The inheritance hierarchy of HTML::FormHandler Fields
.PP
.Vb 10
\&   Text
\&      Money
\&      Password
\&      Hidden
\&      Integer
\&         PosInteger
\&      Float
\&      Date
\&         DateMDY
\&      Email
\&      TextCSV
\&   TextArea
\&   Select
\&      Multiple
\&      SelectCSV
\&      BoolSelect
\&      IntRange
\&         Hour
\&         Minute
\&         MonthDay
\&         Month
\&         Second
\&         Year
\&      MonthName
\&      Weekday
\&   Checkbox
\&      Boolean
\&   Compound
\&      Repeatable
\&      Duration
\&      DateTime
\&   NoValue
\&      Submit
\&      Reset
\&      Button
\&      Display
\&      AddElement
\&      RmElement
\&      NonEditable
\&   PrimaryKey
\&   Upload
\&   File
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A form's 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 \*(L"type\*(R" 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.
.PP
Fields are accessed with \f(CW\*(C`form\->field(\*(Aqname\*(Aq)\*(C'\fR.
Field errors are in \f(CW\*(C`$field\->errors\*(C'\fR.
.PP
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
field's 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.
.PP
.Vb 6
\&    has \*(Aq+field_name_space\*(Aq => ( default => \*(AqMyApp::Form::Field\*(Aq );
\&    has_field \*(Aqname\*(Aq => ( type => \*(AqText\*(Aq ); # HTML::FormHandler::Field::Text
\&    has_field \*(Aqname\*(Aq => ( type => \*(Aq+My::FieldType\*(Aq ); # My::Fieldtype
\&    has_field \*(Aqfoo\*(Aq  => ( type => \*(Aq+Foo\*(Aq );  # MyApp::Form::Field::Foo
\&      or
\&    has_field \*(Aqfoo\*(Aq  => ( type => \*(AqFoo\*(Aq );  # MyApp::Form::Field::Foo
.Ve
.PP
The most basic type is \*(L"Text\*(R", which is usually a 'text' \s-1HTML\s0 element and
a string data type. (If the type of a field is not specified, it will be set to
\&'Text'.)  A \*(L"Select\*(R" field type is a \s-1HTML\s0 select element, and validates against
the list of values provided in the 'options'. A \*(L"Multiple\*(R" type is like \*(L"Select\*(R"
but it allows selecting more than one value at a time.
.PP
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'.
.PP
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.
.SH "Field names"
.IX Header "Field names"
The standard way to use FormHandler is with field names that match your
database accessors. If you want to prepend the \s-1HTML\s0 field names with a
name plus dot, you can set the form 'name' and use the 'html_prefix'
flag. \*(L"$name.\*(R" will be stripped from the beginning of the \s-1HTML\s0 fields
before processing by \s-1HFH,\s0 and will be added back in 'fif'. The field's
\&'html_name' convenience attribute will return this name for use in templates.
.PP
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.
.PP
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'.
.PP
To retrieve a field by name, you can use either the full_name or a
chain: \f(CW\*(C`$form\->field(\*(Aqaddress\*(Aq)\->field(\*(Aqstreet\*(Aq)\->field(\*(Aqstreetname\*(Aq)\*(C'\fR
or: \f(CW\*(C`$form\->field(\*(Aqaddress.street.streetname\*(Aq)\*(C'\fR.
.SH "Creating custom fields"
.IX Header "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.
.PP
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.
.PP
If the field's 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 \s-1HTML\s0 form field.
See HTML::FormHandler::Manual::InflationDeflation for more info.
.PP
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.
.PP
An alternative to new field classes for many field validations might
be roles with collections of validations.
.SH "Other field packages"
.IX Header "Other field packages"
Some custom fields are supplied as \s-1CPAN\s0 packages, in the HTML::FormHandlerX
name space.
.PP
reCAPTCHA
.PP
DateTimeNatural
.PP
\&\s-1URI::HTTP\s0
.SH "Fields supplied by FormHandler"
.IX Header "Fields supplied by FormHandler"
.SS "Basic Fields"
.IX Subsection "Basic Fields"
Although there are a lot of fields provided (probably too many) a lot of them
are \*(L"convenience\*(R" fields or \*(L"name\*(R" 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 won't be used very often.
.PP
The fields in this section are the basic fields, the commonly used fields
that will be most often used in a form.
.PP
\fIText\fR
.IX Subsection "Text"
.PP
A string data type that will be formatted as an \s-1HTML\s0 text field. Has 'minlength'
and 'maxlength' attributes.
.PP
HTML::FormHandler::Field::Text
.PP
\fISelect\fR
.IX Subsection "Select"
.PP
A field formatted as a select element.
.PP
HTML::FormHandler::Field::Select
.PP
\fICheckbox\fR
.IX Subsection "Checkbox"
.PP
A field formatted as a checkbox. If not in params, will be forced to
\&'false' value by 'input_without_param' attribute (0 by default).
.PP
HTML::FormHandler::Field::Checkbox
.PP
\fIHidden\fR
.IX Subsection "Hidden"
.PP
A hidden field.
.PP
HTML::FormHandler::Field::Hidden
.PP
\fIPassword\fR
.IX Subsection "Password"
.PP
A password field. The value is not re-displayed.
.PP
HTML::FormHandler::Field::Password
.PP
\fITextArea\fR
.IX Subsection "TextArea"
.PP
A textarea field.  Has 'cols' and 'rows' attributes.
.PP
HTML::FormHandler::Field::TextArea
.PP
\fIUpload\fR
.IX Subsection "Upload"
.PP
A file upload field that takes a filehandle or a Catalyst upload object (an
object with a 'size' method).
.PP
HTML::FormHandler::Field::Upload
.PP
\fISubmit\fR
.IX Subsection "Submit"
.PP
A submit field.
.PP
HTML::FormHandler::Field::Submit
.PP
\fIReset\fR
.IX Subsection "Reset"
.PP
A reset field.
.PP
HTML::FormHandler::Field::Reset
.SS "Complex Fields (Compound and Repeatable)"
.IX Subsection "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 \s-1HTML\s0 element; they contain
multiple subfields.
.PP
\fICompound\fR
.IX Subsection "Compound"
.PP
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.
.PP
To create a compound field class, you must extend
HTML::FormHandler::Field::Compound and use HTML::FormHandler::Moose to
allow declaring fields:
.PP
.Vb 1
\&  package MyApp::Field::Duration;
\&
\&  use HTML::FormHandler::Moose;
\&  extends \*(AqHTML::FormHandler::Field::Compound\*(Aq;
\&
\&  has_field \*(Aqmonth\*(Aq => (type => \*(AqInteger\*(Aq);
\&  has_field \*(Aqday\*(Aq => ( type => \*(AqInteger\*(Aq );
\&  has_field \*(Aqminutes\*(Aq => ( type => \*(AqInteger\*(Aq );
.Ve
.PP
Then in the form:
.PP
.Vb 1
\&  has_field \*(Aqmy_duration\*(Aq => ( type => \*(Aq+Duration\*(Aq );
.Ve
.PP
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:
.PP
.Vb 1
\&   package MyApp::Form;
\&
\&   use HTML::FormHandler::Moose;
\&   extends \*(AqHTML::FormHandler\*(Aq;
\&
\&   has_field \*(Aqduration\*(Aq => ( type => \*(AqCompound\*(Aq );
\&   has_field \*(Aqduration.month\*(Aq => ( type => \*(AqInteger\*(Aq );
\&   has_field \*(Aqduration.day\*(Aq => ( type => \*(AqInteger\*(Aq );
\&   has_field \*(Aqduration.year\*(Aq => ( type => \*(AqInteger\*(Aq );
.Ve
.PP
In an \s-1HTML\s0 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, \f(CW\*(C`$field\->html_name\*(C'\fR.
.PP
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 \f(CW\*(C`$form\->value\*(C'\fR hash before
\&'update_model' is called.
.PP
See also HTML::FormHandler::Field::Compound.
.PP
\fIRepeatable\fR
.IX Subsection "Repeatable"
.PP
Repeatable fields are used for arrays of compound fields.
.PP
.Vb 5
\&   has_field \*(Aqaddresses\*(Aq => ( type => \*(AqRepeatable\*(Aq );
\&   has_field \*(Aqaddresses.address_id\*(Aq => ( type => \*(AqPrimaryKey\*(Aq );
\&   has_field \*(Aqaddresses.street\*(Aq;
\&   has_field \*(Aqaddresses.city\*(Aq;
\&   has_field \*(Aqaddresses.country\*(Aq => ( type => \*(AqSelect\*(Aq );
.Ve
.PP
The arrays will be built from arrays passed in the params, or from
related ('has_many') rows in the database.
.PP
It is also used for arrays of single fields using the 'contains' keyword:
.PP
.Vb 2
\&  has_field \*(Aqtags\*(Aq => ( type => \*(AqRepeatable\*(Aq );
\&  has_field \*(Aqtags.contains\*(Aq => ( type => \*(Aq+Tag\*(Aq );
.Ve
.PP
See HTML::FormHandler::Field::Repeatable for more information.
.SS "Text Fields"
.IX Subsection "Text Fields"
Fields subclassed from the Text field.
.PP
\fIText\fR
.IX Subsection "Text"
.PP
Text field.
.PP
HTML::FormHandler::Field::Text
.PP
\fIMoney\fR
.IX Subsection "Money"
.PP
Positive or negative real value, formatted to two decimal places.
.PP
HTML::FormHandler::Field::Money
.PP
\fIDate\fR
.IX Subsection "Date"
.PP
Date field that can be used by jQuery datepicker plugin.
.PP
HTML::FormHandler::Field::Date
.PP
\fIDateMDY\fR
.IX Subsection "DateMDY"
.PP
A subclass of 'Date' with the \*(L"%m/%d/%Y\*(R" format.
.PP
HTML::FormHandler::Field::DateMDY
.PP
\fIEmail\fR
.IX Subsection "Email"
.PP
Uses Email::Valid for validation.
.PP
HTML::FormHandler::Field::Email
.PP
\fIInteger\fR
.IX Subsection "Integer"
.PP
Positive and negative integers. Can use range_start and range_end.
.PP
HTML::FormHandler::Field::Integer
.PP
\fIPosInteger\fR
.IX Subsection "PosInteger"
.PP
A positive integer field.
.PP
HTML::FormHandler::Field::PosInteger
.PP
\fIFloat\fR
.IX Subsection "Float"
.PP
Float field that allows you to set size, precision, decimal_symbol, and
decimal_symbol_for_db.
.PP
HTML::FormHandler::Field::Float
.PP
\fITextCSV\fR
.IX Subsection "TextCSV"
.PP
A text field that takes multiple values from a database and converts
them to comma-separated values. This is intended for javascript fields
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.
.PP
HTML::FormHandler::Field::TextCSV
.SS "Compound Fields"
.IX Subsection "Compound Fields"
Fields subclassed from 'Compound'.
.PP
\fICompound\fR
.IX Subsection "Compound"
.PP
HTML::FormHandler::Field::Compound
.PP
\fIRepeatable\fR
.IX Subsection "Repeatable"
.PP
HTML::FormHandler::Field::Repeatable
.PP
\fIDuration\fR
.IX Subsection "Duration"
.PP
Compound field with possible subfields: years, months, weeks, days, hours,
minutes, seconds, nanoseconds.
.PP
HTML::FormHandler::Field::Duration
.PP
\fIDateTime\fR
.IX Subsection "DateTime"
.PP
A compound field that requires you to provide the subfields that
you want. (month/day/year/hour/minutes)
.PP
HTML::FormHandler::Field::DateTime
.SS "Checkbox Fields"
.IX Subsection "Checkbox Fields"
Fields that inherit from 'Checkbox'.
.PP
\fICheckbox\fR
.IX Subsection "Checkbox"
.PP
HTML::FormHandler::Field::Checkbox
.PP
\fIBoolean\fR
.IX Subsection "Boolean"
.PP
Checkbox that return 1 or 0.
.PP
HTML::FormHandler::Field::Boolean
.SS "Select Fields"
.IX Subsection "Select Fields"
Fields that inherit from 'Select'.
.PP
\fISelect\fR
.IX Subsection "Select"
.PP
HTML::FormHandler::Field::Select
.PP
\fIMultiple\fR
.IX Subsection "Multiple"
.PP
Multiple select. Also sorts the selected options to the top of
the select list.
.PP
HTML::FormHandler::Field::Multiple
.SS "SelectCSV"
.IX Subsection "SelectCSV"
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.
.PP
HTML::FormHandler::Field::SelectCSV
.PP
\fIBoolSelect\fR
.IX Subsection "BoolSelect"
.PP
A field with three possible values: empty/0/1.
.PP
HTML::FormHandler::Field::BoolSelect
.PP
\fIHour\fR
.IX Subsection "Hour"
.PP
Integer select range field from 0\-23.
.PP
HTML::FormHandler::Field::Hour
.PP
\fISecond\fR
.IX Subsection "Second"
.PP
Select field with range from 0\-59.
.PP
HTML::FormHandler::Field::Second
.PP
\fIIntRange\fR
.IX Subsection "IntRange"
.PP
An integer select field. Can set label format with 'label_format'.
.PP
HTML::FormHandler::Field::IntRange
.PP
\fIMonth\fR
.IX Subsection "Month"
.PP
Select field with range from 1 \- 12.
.PP
HTML::FormHandler::Field::Month
.PP
\fIMonthDay\fR
.IX Subsection "MonthDay"
.PP
Select field with range from 1 \- 31.
.PP
HTML::FormHandler::Field::MonthDay
.PP
\fIMonthName\fR
.IX Subsection "MonthName"
.PP
Select field with month name labels, value 1\-12.
.PP
HTML::FormHandler::Field::MonthName
.PP
\fIMinute\fR
.IX Subsection "Minute"
.PP
Select field with range from 0\-59.
.PP
HTML::FormHandler::Field::Minute
.PP
\fIWeekday\fR
.IX Subsection "Weekday"
.PP
A select field where the labels are the names of the week, and the
values are 0\-6.
.PP
HTML::FormHandler::Field::Weekday
.PP
\fIYear\fR
.IX Subsection "Year"
.PP
Select field providing year list 5 years back and 10 years forward.
.PP
HTML::FormHandler::Field::Year
.SS "NoValue fields"
.IX Subsection "NoValue fields"
Fields that inherit from 'NoValue'. None of these fields will
provide a 'value' in the \f(CW\*(C`$form\->value\*(C'\fR hashref.
.PP
\fINoValue\fR
.IX Subsection "NoValue"
.PP
Base class for fields that don't produce a 'value'.
.PP
HTML::FormHandler::Field::NoValue
.PP
\fISubmit\fR
.IX Subsection "Submit"
.PP
HTML::FormHandler::Field::Submit
.PP
\fIReset\fR
.IX Subsection "Reset"
.PP
HTML::FormHandler::Field::Reset
.PP
\fIButton\fR
.IX Subsection "Button"
.PP
Button field that is rendered by the Button widget.
.PP
HTML::FormHandler::Field::Button
.PP
\fIDisplay\fR
.IX Subsection "Display"
.PP
Non-data field used for inserting \s-1HTML\s0 into the form. Probably
now better handled by a Block or a rendering tag.
.PP
HTML::FormHandler::Field::Display
.PP
\fIAddElement\fR
.IX Subsection "AddElement"
.PP
Example field for adding a repeatable element.
.PP
HTML::FormHandler::Field::AddElement
.PP
\fIRmElement\fR
.IX Subsection "RmElement"
.PP
Example field for removing a repeatable element
.PP
HTML::FormHandler::Field::RmElement
.PP
\fINonEditable\fR
.IX Subsection "NonEditable"
.PP
For Bootstrap-style non-editable fields.
.SS "TextArea fields"
.IX Subsection "TextArea fields"
Fields that inherit from 'TextArea'.
.PP
\fITextArea\fR
.IX Subsection "TextArea"
.PP
HTML::FormHandler::Field::TextArea
.SS "Password fields"
.IX Subsection "Password fields"
\fIPassword\fR
.IX Subsection "Password"
.PP
Password field. Sets 'noupdate' flag if empty and not required.
.PP
HTML::FormHandler::Field::Password
.PP
\fIPasswordConf\fR
.IX Subsection "PasswordConf"
.PP
Password confirmation field.
.PP
HTML::FormHandler::Field::PasswordConf
.SS "Other fields"
.IX Subsection "Other fields"
These fields inherit just from 'Field'.
.PP
\fIFile\fR
.IX Subsection "File"
.PP
A file field that does no processing. Most people probably want to
use 'Upload' instead.
.PP
HTML::FormHandler::Field::File
.PP
\fIPrimaryKey\fR
.IX Subsection "PrimaryKey"
.PP
Hidden field that provides the primary key for Repeatable fields.
.PP
HTML::FormHandler::Field::PrimaryKey
.PP
\fICaptcha\fR
.IX Subsection "Captcha"
.PP
A Captcha field using GD::SecurityImage. Requires the use of the
HTML::FormHandler::TraitFor::Captcha role, or similar code.
.PP
HTML::FormHandler::Field::Captcha
.SH "AUTHOR"
.IX Header "AUTHOR"
FormHandler Contributors \- see HTML::FormHandler
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2017 by Gerda Shank.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.