Provided by: libhtml-formhandler-perl_0.40068-1_all bug

NAME

       HTML::FormHandler::Manual::Fields - brief documentation of available fields

VERSION

       version 0.40068

SYNOPSIS

       Manual Index

       See also HTML::FormHandler::Field for a description of the base field attributes.

       The inheritance hierarchy of HTML::FormHandler Fields

          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

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 "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 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.

           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
             or
           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.

Field names

       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 field's '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 chain:
       "$form->field('address')->field('street')->field('streetname')" or:
       "$form->field('address.street.streetname')".

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 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 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 name space.

       reCAPTCHA

       DateTimeNatural

       URI::HTTP

Fields supplied by FormHandler

   Basic Fields
       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 won't 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.

       Text

       A string data type that will be formatted as an HTML text field. Has 'minlength' and
       'maxlength' attributes.

       HTML::FormHandler::Field::Text

       Select

       A field formatted as a select element.

       HTML::FormHandler::Field::Select

       Checkbox

       A field formatted as a checkbox. If not in params, will be forced to 'false' value by
       'input_without_param' attribute (0 by default).

       HTML::FormHandler::Field::Checkbox

       Hidden

       A hidden field.

       HTML::FormHandler::Field::Hidden

       Password

       A password field. The value is not re-displayed.

       HTML::FormHandler::Field::Password

       TextArea

       A textarea field.  Has 'cols' and 'rows' attributes.

       HTML::FormHandler::Field::TextArea

       Upload

       A file upload field that takes a filehandle or a Catalyst upload object (an object with a
       'size' method).

       HTML::FormHandler::Field::Upload

       Submit

       A submit field.

       HTML::FormHandler::Field::Submit

       Reset

       A reset field.

       HTML::FormHandler::Field::Reset

   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 multiple subfields.

       Compound

       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:

         package MyApp::Field::Duration;

         use HTML::FormHandler::Moose;
         extends 'HTML::FormHandler::Field::Compound';

         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:

          package MyApp::Form;

          use HTML::FormHandler::Moose;
          extends 'HTML::FormHandler';

          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

       Repeatable fields are used for arrays of compound fields.

          has_field 'addresses' => ( type => 'Repeatable' );
          has_field 'addresses.address_id' => ( type => 'PrimaryKey' );
          has_field 'addresses.street';
          has_field 'addresses.city';
          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.

   Text Fields
       Fields subclassed from the Text field.

       Text

       Text field.

       HTML::FormHandler::Field::Text

       Money

       Positive or negative real value, formatted to two decimal places.

       HTML::FormHandler::Field::Money

       Date

       Date field that can be used by jQuery datepicker plugin.

       HTML::FormHandler::Field::Date

       DateMDY

       A subclass of 'Date' with the "%m/%d/%Y" format.

       HTML::FormHandler::Field::DateMDY

       Email

       Uses Email::Valid for validation.

       HTML::FormHandler::Field::Email

       Integer

       Positive and negative integers. Can use range_start and range_end.

       HTML::FormHandler::Field::Integer

       PosInteger

       A positive integer field.

       HTML::FormHandler::Field::PosInteger

       Float

       Float field that allows you to set size, precision, decimal_symbol, and
       decimal_symbol_for_db.

       HTML::FormHandler::Field::Float

       TextCSV

       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.

       HTML::FormHandler::Field::TextCSV

   Compound Fields
       Fields subclassed from 'Compound'.

       Compound

       HTML::FormHandler::Field::Compound

       Repeatable

       HTML::FormHandler::Field::Repeatable

       Duration

       Compound field with possible subfields: years, months, weeks, days, hours, minutes,
       seconds, nanoseconds.

       HTML::FormHandler::Field::Duration

       DateTime

       A compound field that requires you to provide the subfields that you want.
       (month/day/year/hour/minutes)

       HTML::FormHandler::Field::DateTime

   Checkbox Fields
       Fields that inherit from 'Checkbox'.

       Checkbox

       HTML::FormHandler::Field::Checkbox

       Boolean

       Checkbox that return 1 or 0.

       HTML::FormHandler::Field::Boolean

   Select Fields
       Fields that inherit from 'Select'.

       Select

       HTML::FormHandler::Field::Select

       Multiple

       Multiple select. Also sorts the selected options to the top of the select list.

       HTML::FormHandler::Field::Multiple

   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.

       HTML::FormHandler::Field::SelectCSV

       BoolSelect

       A field with three possible values: empty/0/1.

       HTML::FormHandler::Field::BoolSelect

       Hour

       Integer select range field from 0-23.

       HTML::FormHandler::Field::Hour

       Second

       Select field with range from 0-59.

       HTML::FormHandler::Field::Second

       IntRange

       An integer select field. Can set label format with 'label_format'.

       HTML::FormHandler::Field::IntRange

       Month

       Select field with range from 1 - 12.

       HTML::FormHandler::Field::Month

       MonthDay

       Select field with range from 1 - 31.

       HTML::FormHandler::Field::MonthDay

       MonthName

       Select field with month name labels, value 1-12.

       HTML::FormHandler::Field::MonthName

       Minute

       Select field with range from 0-59.

       HTML::FormHandler::Field::Minute

       Weekday

       A select field where the labels are the names of the week, and the values are 0-6.

       HTML::FormHandler::Field::Weekday

       Year

       Select field providing year list 5 years back and 10 years forward.

       HTML::FormHandler::Field::Year

   NoValue fields
       Fields that inherit from 'NoValue'. None of these fields will provide a 'value' in the
       "$form->value" hashref.

       NoValue

       Base class for fields that don't produce a 'value'.

       HTML::FormHandler::Field::NoValue

       Submit

       HTML::FormHandler::Field::Submit

       Reset

       HTML::FormHandler::Field::Reset

       Button

       Button field that is rendered by the Button widget.

       HTML::FormHandler::Field::Button

       Display

       Non-data field used for inserting HTML into the form. Probably now better handled by a
       Block or a rendering tag.

       HTML::FormHandler::Field::Display

       AddElement

       Example field for adding a repeatable element.

       HTML::FormHandler::Field::AddElement

       RmElement

       Example field for removing a repeatable element

       HTML::FormHandler::Field::RmElement

       NonEditable

       For Bootstrap-style non-editable fields.

   TextArea fields
       Fields that inherit from 'TextArea'.

       TextArea

       HTML::FormHandler::Field::TextArea

   Password fields
       Password

       Password field. Sets 'noupdate' flag if empty and not required.

       HTML::FormHandler::Field::Password

       PasswordConf

       Password confirmation field.

       HTML::FormHandler::Field::PasswordConf

   Other fields
       These fields inherit just from 'Field'.

       File

       A file field that does no processing. Most people probably want to use 'Upload' instead.

       HTML::FormHandler::Field::File

       PrimaryKey

       Hidden field that provides the primary key for Repeatable fields.

       HTML::FormHandler::Field::PrimaryKey

       Captcha

       A Captcha field using GD::SecurityImage. Requires the use of the
       HTML::FormHandler::TraitFor::Captcha role, or similar code.

       HTML::FormHandler::Field::Captcha

AUTHOR

       FormHandler Contributors - see HTML::FormHandler

COPYRIGHT AND LICENSE

       This software is copyright (c) 2017 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.