NAME¶
HTML::FormHandler::Field - base class for fields
VERSION¶
version 0.40057
SYNOPSIS¶
Instances of Field subclasses are generally built by HTML::FormHandler from
'has_field' declarations or the field_list, but they can also be constructed
using new for test purposes (since there's no standard way to add a field to a
form after construction).
use HTML::FormHandler::Field::Text;
my $field = HTML::FormHandler::Field::Text->new( name => $name, ... );
In your custom field class:
package MyApp::Field::MyText;
use HTML::FormHandler::Moose;
extends 'HTML::FormHandler::Field::Text';
has 'my_attribute' => ( isa => 'Str', is => 'rw' );
apply [ { transform => sub { ... } },
{ check => ['fighter', 'bard', 'mage' ], message => '....' }
];
1;
DESCRIPTION¶
This is the base class for form fields. The 'type' of a field class is used in
the FormHandler field_list or has_field to identify which field class to load
from the 'field_name_space' (or directly, when prefixed with '+'). If the type
is not specified, it defaults to Text.
See HTML::FormHandler::Manual::Fields for a list of the fields and brief
descriptions of their structure.
ATTRIBUTES¶
Names, types, accessor¶
- name
- The name of the field. Used in the HTML form. Often a db accessor. The
only required attribute.
- type
- The class or type of the field. The 'type' of
HTML::FormHandler::Field::Money is 'Money'. Classes that you define
yourself are prefixed with '+'.
- accessor
- If the name of your field is different than your database accessor, use
this attribute to provide the accessor.
- full_name
- The name of the field with all parents:
'event.start_date.month'
- full_accessor
- The field accessor with all parents.
- html_name
- The full_name plus the form name if 'html_prefix' is set.
- input_param
- By default we expect an input parameter based on the field name. This
allows you to look for a different input parameter.
Field data¶
- inactive, is_inactive, is_active
- Set the 'inactive' attribute to 1 if this field is inactive. The
'inactive' attribute that isn't set or is set to 0 will make a field
'active'. This provides a way to define fields in the form and selectively
set them to inactive. There is also an '_active' attribute, for internal
use to indicate that the field has been activated/inactivated on 'process'
by the form's 'active'/'inactive' attributes.
You can use the is_inactive and is_active methods to check whether this
particular field is active.
if( $form->field('foo')->is_active ) { ... }
- input
- The input string from the parameters passed in.
- value
- The value as it would come from or go into the database, after being acted
on by inflations/deflations and transforms. Used to construct the
"$form->values" hash. Validation and constraints act on
'value'.
See also HTML::FormHandler::Manual::InflationDeflation.
- fif
- Values used to fill in the form. Read only. Use a deflation to get from
'value' to 'fif' if an inflator was used. Use 'fif_from_value' attribute
if you want to use the field 'value' to fill in the form.
[% form.field('title').fif %]
- init_value
- Initial value populated by init_from_object. You can tell if a field has
changed by comparing 'init_value' and 'value'. Read only.
- input_without_param
- Input for this field if there is no param. Set by default for Checkbox,
and Select, since an unchecked checkbox or unselected pulldown does not
return a parameter.
- form
- A reference to the containing form.
- parent
- A reference to the parent of this field. Compound fields are the parents
for the fields they contain.
Errors¶
- errors
- Returns the error list for the field. Also provides 'num_errors',
'has_errors', 'push_errors' and 'clear_errors' from Array trait. Use
'add_error' to add an error to the array if you want to use a MakeText
language handle. Default is an empty list.
- add_error
- Add an error to the list of errors. Error message will be localized using
'_localize' method. See also HTML::FormHandler::TraitFor::I18N.
return $field->add_error( 'bad data' ) if $bad;
- error_fields
- Compound fields will have an array of errors from the subfields.
- localize_meth
- Set the method used to localize.
Attributes for creating HTML¶
The 'element_attr' hashref attribute can be used to set arbitrary HTML
attributes on a field's input tag.
has_field 'foo' => ( element_attr => { readonly => 1, my_attr => 'abc' } );
Note that the 'id' and 'type' attributes are not set using element_attr. Use the
field's 'id' attribute (or 'build_id_method') to set the id.
The 'label_attr' hashref is for label attributes, and the 'wrapper_attr' is for
attributes on the wrapping element (a 'div' for the standard 'simple'
wrapper).
A 'javascript' key in one of the '_attr' hashes will be inserted into the
element as-is.
The following are used in rendering HTML, but are handled specially.
label - Text label for this field. Defaults to ucfirst field name.
build_label_method - coderef for constructing the label
wrap_label_method - coderef for constructing a wrapped label
id - Useful for javascript (default is html_name. to prefix with
form name, use 'html_prefix' in your form)
build_id_method - coderef for constructing the id
render_filter - Coderef for filtering fields before rendering. By default
changes >, <, &, " to the html entities
disabled - Boolean to set field disabled
The order attribute may be used to set the order in which fields are rendered.
order - Used for sorting errors and fields. Built automatically,
but may also be explicitly set
The following are discouraged. Use 'element_attr', 'label_attr', and
'wrapper_attr' instead.
title - instead use element_attr => { title => '...' }
style - instead use element_attr => { style => '...' }
tabindex - instead use element_attr => { tabindex => 1 }
readonly - instead use element_attr => { readonly => 'readonly' }
Rendering of the various HTML attributes is done by calling the 'process_attrs'
function (from HTML::FormHandler::Render::Util) and passing in a method that
adds in error classes, provides backward compatibility with the deprecated
attributes, etc.
attribute hashref class attribute wrapping method
================= ================= ================
element_attr element_class element_attributes
label_attr label_class label_attributes
wrapper_attr wrapper_class wrapper_attributes
element_wrapper_class element_wrapper_attributes
('element_wrapper' is for an inner div around the input element, not including
the label. Used for Bootstrap3 rendering, but also available in the Simple
wrapper.) The slots for the class attributes are arrayrefs; they will coerce a
string into an arrayref. In addition, these 'wrapping methods' call a hook
method in the form class, 'html_attributes', which you can use to customize
and localize the various attributes. (Field types: 'element', 'wrapper',
'label')
sub html_attributes {
my ( $self, $field, $type, $attr ) = @_;
$attr->{class} = 'label' if $type eq 'label';
return $attr;
}
The 'process_attrs' function will also handle an array of strings, such as for
the 'class' attribute.
A hashref containing flags and strings for use in the rendering code. The value
of a tag can be a string, a coderef (accessed as a method on the field) or a
block specified with a percent followed by the blockname ('%blockname').
Retrieve a tag with 'get_tag'. It returns a '' if the tag doesn't exist.
This attribute used to be named 'widget_tags', which is deprecated.
html5_type_attr [string]¶
This string is used when rendering an input element as the value for the type
attribute. It is used when the form has the is_html5 flag on.
The 'widget' attribute is used in rendering, so if you are not using
FormHandler's rendering facility, you don't need this attribute. It is used in
generating HTML, in templates and the rendering roles. Fields of different
type can use the same widget.
This attribute is set in the field classes, or in the fields defined in the
form. If you want a new widget type, create a widget role, such as
MyApp::Form::Widget::Field::MyWidget. Provide the name space in the
'widget_name_space' attribute, and set the 'widget' of your field to the
package name after the Field/Form/Wrapper:
has_field 'my_field' => ( widget => 'MyWidget' );
If you are using a template based rendering system you will want to create a
widget template. (see HTML::FormHandler::Manual::Templates)
Widget types for some of the provided field classes:
Widget : Field classes
-----------------------:---------------------------------
Text : Text, Integer
Checkbox : Checkbox, Boolean
RadioGroup : Select, Multiple, IntRange (etc)
Select : Select, Multiple, IntRange (etc)
CheckboxGroup : Multiple select
TextArea : TextArea
Compound : Compound, Repeatable, DateTime
Password : Password
Hidden : Hidden
Submit : Submit
Reset : Reset
NoRender :
Upload : Upload
Widget roles are automatically applied to field classes unless they already have
a 'render' method, and if the 'no_widgets' flag in the form is not set.
You can create your own widget roles and specify the namespace in
'widget_name_space'. In the form:
has '+widget_name_space' => ( default => sub { ['MyApp::Widget'] } );
If you want to use a fully specified role name for a widget, you can prefix it
with a '+':
widget => '+MyApp::Widget::SomeWidget'
For more about widgets, see HTML::FormHandler::Manual::Rendering.
Flags¶
password - prevents the entered value from being displayed in the form
writeonly - The initial value is not taken from the database
noupdate - Do not update this field in the database (does not appear in $form->value)
Defaults¶
See also the documentation on "Defaults" in
HTML::FormHandler::Manual::Intro.
- default_method, set_default
- Supply a coderef (which will be a method on the field) with
'default_method' or the name of a form method with 'set_default' (which
will be a method on the form). If not specified and a form method with a
name of "default_<field_name>" exists, it will be
used.
- default
- Provide an initial value just like the 'set_default' method, except in the
field declaration:
has_field 'bax' => ( default => 'Default bax' );
FormHandler has flipped back and forth a couple of times about whether a
default specified in the has_field definition should override values
provided in an initial item or init_object. Sometimes people want one
behavior, and sometimes the other. Now 'default' does *not* override.
If you pass in a model object with "item => $row" or an initial
object with "init_object => {....}" the values in that object
will be used instead of values provided in the field definition with
'default' or 'default_fieldname'. If you want defaults that override or
supplement the item/init_object, you can use the form flags
'use_defaults_over_obj', 'use_init_obj_over_item', and
'use_init_obj_when_no_accessor_in_item'.
You could also put your defaults into your row or init_object instead.
- default_over_obj
- This is deprecated; look into using 'use_defaults_over_obj' or
'use_init_obj_over_item' flags instead. They allow using the standard
'default' attribute.
Allows setting defaults which will override values provided with an
item/init_object. (And only those. Will not be used for defaults without
an item/init_object.)
has_field 'quux' => ( default_over_obj => 'default quux' );
At this time there is no equivalent of 'set_default', but the type of the
attribute is not defined so you can provide default values in a variety of
other ways, including providing a trait which does
'build_default_over_obj'. For examples, see tests in the
distribution.
Constraints and Validations¶
See also HTML::FormHandler::Manual::Validation.
Constraints set in attributes¶
- required
- Flag indicating whether this field must have a value
- unique
- For DB field - check for uniqueness. Action is performed by the DB
model.
- messages
-
messages => { required => '...', unique => '...' }
Set messages created by FormHandler by setting in the 'messages' hashref.
Some field subclasses have additional settable messages.
required: Error message text added to errors if required field is not
present. The default is "Field <field label> is
required".
- range_start
- range_end
- Field values are validated against the specified range if one or both of
range_start and range_end are set and the field does not have 'options'.
The IntRange field uses this range to create a select list with a range of
integers.
In a FormHandler field_list:
age => {
type => 'Integer',
range_start => 18,
range_end => 120,
}
- not_nullable
- Fields that contain 'empty' values such as '' are changed to undef in the
validation process. If this flag is set, the value is not changed to
undef. If your database column requires an empty string instead of a null
value (such as a NOT NULL column), set this attribute.
has_field 'description' => (
type => 'TextArea',
not_nullable => 1,
);
This attribute is also used when you want an empty array to stay an empty
array and not be set to undef.
It's also used when you have a compound field and you want the 'value'
returned to contain subfields with undef, instead of the whole field to be
undef.
apply¶
Use the 'apply' keyword to specify an ArrayRef of constraints and coercions to
be executed on the field at validate_field time.
has_field 'test' => (
apply => [ 'MooseType',
{ check => sub {...}, message => { } },
{ transform => sub { ... lc(shift) ... } }
],
);
See more documentation in HTML::FormHandler::Manual::Validation.
trim¶
An action to trim the field. By default this contains a transform to strip
beginning and trailing spaces. Set this attribute to null to skip trimming, or
supply a different transform.
trim => { transform => sub {
my $string = shift;
$string =~ s/^\s+//;
$string =~ s/\s+$//;
return $string;
} }
trim => { type => MyTypeConstraint }
Trimming is performed before any other defined actions.
Inflation/deflation¶
There are a number of methods to provide finely tuned inflation and deflation:
- inflate_method
- Inflate to a data format desired for validation.
- deflate_method
- Deflate to a string format for presenting in HTML.
- inflate_default_method
- Modify the 'default' provided by an 'item' or 'init_object'.
- deflate_value_method
- Modify the value returned by "$form->value".
- deflation
- Another way of providing a deflation method.
- transform
- Another way of providing an inflation method.
Normally if you have a deflation, you will need a matching inflation. There are
two different flavors of inflation/deflation: one for inflating values to a
format needed for validation and deflating for output, the other for inflating
the initial provided values (usually from a database row) and deflating them
for the 'values' returned.
See HTML::FormHandler::Manual::InflationDeflation.
Processing and validating the field¶
validate_field¶
This is the base class validation routine. Most users will not do anything with
this. It might be useful for method modifiers, if you want code that executed
before or after the validation process.
validate¶
This field method can be used in addition to or instead of 'apply' actions in
custom field classes. It should validate the field data and set error messages
on errors with "$field->add_error".
sub validate {
my $field = shift;
my $value = $field->value;
return $field->add_error( ... ) if ( ... );
}
validate_method, set_validate¶
Supply a coderef (which will be a method on the field) with 'validate_method' or
the name of a form method with 'set_validate' (which will be a method on the
form). If not specified and a form method with a name of
"validate_<field_name>" exists, it will be used.
Periods in field names will be replaced by underscores, so that the field
'addresses.city' will use the 'validate_addresses_city' method for validation.
has_field 'my_foo' => ( validate_method => \&my_foo_validation );
sub my_foo_validation { ... }
has_field 'title' => ( isa => 'Str', set_validate => 'check_title' );
AUTHOR¶
FormHandler Contributors - see HTML::FormHandler
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2014 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.