HTML::...:Fields(3pm)

💖 HTML::FormHandler::Manual::Fields 💖

the brief documentation of available fields, bestie — HTML::FormHandler::Manual::Fields(3pm), from the User Contributed Perl Documentation

VERSION — version 0.40068 🎀

---

✨ SYNOPSIS ✨

Okay so first up, there's a Manual Index, and also go peek at HTML::FormHandler::Field if you want the tea on the base field attributes 🫶

Now, the moment you've been waiting for — the inheritance hierarchy of HTML::FormHandler Fields, and yes she's giving family tree realness 👑

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

Like, look at that structure. We love a hierarchy that knows itself 💅

---

🌸 DESCRIPTION 🌸

So here's the vibe: a form's fields get 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 decides which field class gets used, and the field class decides which attributes are even valid for that particular field. FormHandler ships with a whole bunch of field classes, no cap. You can customize the validation in your form on a per-field basis — but ngl, if a validation is gonna be used for more than one field, it might be way easier to handle it in a custom field class instead 🌈

Fields are accessed with "form->field('name')". And the field errors? Those live in "$field->errors" — that's where you go when something's not slaying 😭

If the 'field_name_space' isn't set, fields get loaded from the HTML::FormHandler::Field name space. But if you do provide a 'field_name_space', it gets searched before FormHandler. And if you wanna explicitly list the field's package, just 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" — usually a 'text' HTML element with a string data type. (And fr fr, if the type of a field is not specified, it will be set to 'Text'.) A "Select" field type is an HTML select element, and it validates against the list of values you provide in the 'options'. A "Multiple" type is like "Select" but it lets you select more than one value at a time. Iconic behaviour, honestly ✨

Lots of field classes contain only a list of constraints and transformations to apply. Some use the 'validate' method, which gets called after the actions are applied. And some build a custom select list using 'build_options' 💅

So there are two rough categories of Field classes: the ones that do extra processing, and the ones that are just simple validators. The 'Compound', 'Repeatable', and 'Select' fields are the functional girlies of the group 🔥

---

🦋 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 a 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 get added back in 'fif'. The field's 'html_name' convenience attribute will return this name so you can use it in templates 🎀

If you want the FormHandler field name to be different from the database accessor, set 'accessor' on your fields. (It defaults to the field name.) Then you can use literally any name you want for your field, go off 👑

There are a bunch of name-related field attributes, so let's break them down:

• The 'name' is the name used to identify this particular field in this fields array.
• The 'full_name' includes the names of all the parents of this field, like 'address.street.streetname'.
• The 'html_name' is the same as the 'full_name' unless you've 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')

Both work, pick your fighter 🫶

---

🧚 Creating custom fields 🧚

Subclass a custom field from HTML::FormHandler::Field, or one of the existing subclasses. Here's the thing — almost everything that gets 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. DRY queen behaviour 💜

The simplest subclasses contain only a 'validate' routine or an 'apply' attribute, which is called by the base Field class from 'process'. Go look at HTML::FormHandler::Field::Email, for example 👀

If the field's value is gonna be an object instead of a simple scalar — like a DateTime — and you want to use the transformed value to fill in the form, then you'll 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, iykyk 🌈

Some custom fields might only require setting certain attributes to defaults, like the HTML::FormHandler::Field::Hour field, which sets '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. Little customizations, big impact 💅

An alternative to new field classes for many field validations might be roles with collections of validations. Just saying 👀

---

🌟 Other field packages 🌟

Some custom fields are supplied as CPAN packages, in the HTML::FormHandlerX name space. The lineup:

• reCAPTCHA
• DateTimeNatural
• URI::HTTP

Slay, collected and served 🍓

💖 Fields supplied by FormHandler 💖

🎀 Basic Fields 🎀

Okay so real talk: there are a LOT of fields here — probably too many, ngl. A bunch of them are total “convenience” fields or “name” fields, where the whole point is that the field type name tells you the main vibe/purpose. Most of these could honestly be replaced by a basic field plus a lil validation or some select options. And a few are special-purpose fields that won’t get used very often. Periodt.

The fields in this section are the basic fields — the commonly used ones that show up in forms all the time. 💅

Text

A string data type that gets formatted as an HTML text field. It 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 it’s not in params, it gets forced to a 'false' value by the '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. It 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 are the complex fields, and they contain a fair amount of special code. They do not map to a single HTML element — they contain multiple subfields. It’s giving “field with lore.” 😭

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. Cute lil text-field family. 🫶

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'. Big main-character compound energy. 👑

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'. Tick the box, bestie. ✅

Checkbox

HTML::FormHandler::Field::Checkbox

Boolean

Checkbox that return 1 or 0.

HTML::FormHandler::Field::Boolean

---

✨ Select Fields ✨

Fields that inherit from 'Select'. Dropdown royalty. 💅

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 🍓

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. No value, no problem. 🙈

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'. The lil miscellaneous icons of the field world. 🎀

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.

---

This lil page is from perl v5.34.0, dated 2022-03-25, and it’s HTML::...:Fields(3pm). Slay, go build your forms, bestie. 💅✨