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.
Fielddata
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,parent
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.
AttributesforcreatingHTML
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.
tags
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.
widget
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.
Install Now
PNG Icons