Provided by: libhtml-formhandler-perl_0.40068-1_all
HTML::FormHandler::Manual::Fields - brief documentation of available fields
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
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.
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
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.