/ 
HTML-FormHandler-0.22
River stage two • 21 direct dependents • 31 total dependents
/ HTML::FormHandler::Field

NAME

HTML::FormHandler::Field - Base class for HTML::FormHandler Fields

SYNOPSIS

Instances of Field subclasses are generally built by HTML::FormHandler from the field_list, but they can also be constructed using new.

use HTML::FormHandler::Field::Text;
my $field = HTML::FormHandler::Field::Text->new( name => $name, ... );

In your custom field class:

package MyApp::Field::MyText;
extends 'HTML::FormHandler::Field::Text';

has 'my_attribute' => ( isa => 'Str', is => 'rw' );
sub validate { ... }
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.

A number of field classes are provided by the distribution. The basic field types are:

Text
Integer
Select
Boolean

These field types alone would be enough for most applications, since the equivalent of the others could be defined using field attributes and custom validation methods. There is some benefit to having descriptive names, of course, and if you have multiple fields requiring the same validation, you should certainly define a custom field class.

Inheritance hierarchy of the distribution's field classes:

Text
   Money
   Password
   Integer
      PosInteger
TextArea
   HtmlArea
Select
   Multiple
   IntRange
      Hour
      Minute
      MonthDay
      Month
      Second
      Year
   MonthName 
   Weekday
      WeekdayStr
Boolean
   Checkbox
DateMDY
DateTime
Email

See the documentation or source for the individual fields.

Normally you would implement a 'validate' routine in a custom field class, but you can also override the base validation process by overriding 'process'.

ATTRIBUTES

name

Field name. If this is a database form, this name is usually a database column/accessor name or relationship.

type

Field type (e.g. 'Text', 'Select' ... ) from a HTML::FormHandler::Field subclass, either one provided in the distribution or one that you create yourself, proceded by a "+": type => '+MetaText'

init_value

Initial value populated by init_from_object. You can tell if a field has changed by comparing 'init_value' and 'value'. Not to be confused with the form method init_value(). Not set by user.

value

The initial value of the field from the database (or init_object), and the changed value after form validation. A change in this attribute triggers setting the 'fif' attribute.

The "validate" field method usually sets this value if the field validates.

The user does not need to set this field except in validation methods.

parent

A reference to the parent of this field.

errors_on_parent

Flag indicating that errors should not be set on this field class

input

Input value for the field, moved from the parameter hash. In HTML::FormHandler, the setter for this attribute is for internal use. If you want to set an input value, use the 'set_param' method. A field validation routine may copy the value of this attribute to the 'value' attribute. The setter may be used in field tests and if a field class is used standalone. A change in this attribute triggers setting 'fif'.

input_without_param

Input for this field if there is no param. Needed for checkbox, since an unchecked checkbox does not return a parameter.

fif

For filling in forms. Input or value. The user does not need to set this field. It is set by FormHandler from the values in your database object or the input parameters. The normal use would be to access this field from a template:

[% f = form.field('title') %]
[% f.fif %]

accessor

If the name of your field is different than your database accessor, use this attribute to provide the name of accessor.

temp

Temporary attribute. Not used by HTML::FormHandler.

label

Text label for this field. Useful in templates. Defaults to ucfirst field name.

title

Place to put title for field, for mouseovers. Not used by F::P.

style

Field's generic style to use for css formatting in templates. Not actually used by F::P.

css_class

Field's css_class for use in templates.

form

A reference to the containing form.

html_name

Field name for use in HTML. If 'html_prefix' in the form has been set the name will prefixed by the form name and a dot, otherwise this attribute is the equivalient of 'full_name'. A field named "street" in a form named "address" would have a html_name of "address.street". Allows multiple forms with the same field names.

widget

The 'widget' is attribute is not used by base FormHandler code. It is intended for use 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.

Widget types for the provided field classes:

Widget      : Field classes 
------------:-----------------------------------
text        : Text, Integer
checkbox    : Checkbox, Select
radio       : Boolean, Select
select      : Select, Multiple
textarea    : TextArea, HtmlArea
compound    : DateTime
password    : Password

The 'Select' field class has a 'select_widget' method that chooses which widget to use, which could be called by templates or rendering roles.

The default widget is 'text'.

order

This is the field's order used for sorting errors and field lists. See the "set_order" method and F::P method "sorted_fields". The order field is set for the fields when the form is built, but if the fields are defined with a hashref the order will not be defined. The "auto" and "fields" field_list attributes will take an arrayref which will preserve the order. If you explicitly set "order" on the fields in a field_list, you should set it on all the fields, otherwise results will be unpredictable.

required

Flag indicating whether this field must have a value

required_message

Error message text added to errors if required field is not present

The default is "Field <field label> is required".

unique

Flag to initiate checks in the database model for uniqueness.

unique_message

Error message text added to errors if field is not unique

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,
}

Or just set one:

age => {
    type            => 'Integer',
    range_start     => 18,
}

Range checks are done after validation so must only be used on appropriate fields

id, build_id

Provides an 'id' for the field. Useful for javascript. The default id is:

$field->form->name . $field->id

Override with "build_id".

javascript

Store javascript for the field

password

This is a boolean flag to prevent the field from being returned in the $form-fif> and $field-fif> methods.

writeonly

Fields flagged 'writeonly' are not returned in the 'fif' methods from the field's initial value, even if a value for the field exists in the item. The value is not read from the database. However, the value entered into the form WILL be returned. This might be used for columns that should only be written to the database on updates.

clear

This is a flag that says you want to set the database column to null for this field. Validation is also not run on this field.

disabled

readonly

These allow you to enter hints about how the html element is generated.

HTML::FormHandler does not use these attributes; they are for your convenience in constructing HTML.

noupdate

This boolean flag indicates a field that should not be updated. Fields flagged as noupdate are skipped when processed by the model.

This is useful when a form contains extra fields that are not directly written to the data store.

errors

Returns the error list for the field. Also provides 'num_errors', 'has_errors', 'push_errors' and 'clear_errors' from Collection::Array metaclass. Use 'add_error' to add an error to the array if you want to use a MakeText language handle. Default is an empty list.

set_validate

Specify the form method to be used to validate this field. The default is 'validate_' . $field->name. (Periods in field names will be changed to underscores.) If you have a number of fields that require the same validation and don't want to write a field class, you could set them all to the same method name.

has_field 'title' => ( isa => 'Str', set_validate => 'check_title' );
has_field 'subtitle' => ( isa => 'Str', set_validate => 'check_title' );

set_init

The name of the method in the form that provides a field's initial value

apply

Use the 'apply' keyword to specify an ArrayRef of constraints and coercions to be executed on the field at process time.

has_field 'test' => ( 
   apply => [ 'MooseType', { check => sub {...}, message => { } } 
);

In general the action can be of three types: a Moose type (which is represented by it's name), a transformation (which is a callback called on the value of the field), or a constraint ('check') which performs a 'smart match' on the value of the field. Currently we implement the smart match in our code - but in the future when Perl 5.10 is more widely used we'll switch to the core http://search.cpan.org/~rgarcia/perl-5.10.0/pod/perlsyn.pod#Smart_matching_in_detail smart match operator.

The Moose type action first tries to coerce the value - then it checks the result, so you can use it instead of both constraints and tranformations - TIMTOWTDI. For most constraints and transformations it is your choice as to whether you use a Moose type or use a 'check' or 'transform'.

All three types define a message to be presented to the user in the case of failure. Transformations and coercions are called in an eval to catch the errors. Warnings are also trapped.

All the actions are called in the order that they are defined, so that you can check constraints after transformations and vice versa. You can weave all three types of actions in any order you need. The actions specified with 'apply' will be stored in an 'actions' array.

To declare actions inside a field class use HTML::FormHandler::Moose and 'apply' sugar:

package MyApp::Field::Test;
use HTML::FormHandler::Moose;
extends 'HTML::FormHandler::Field;

apply [ 'SomeConstraint', { check => ..., message => .... } ];

1;

Actions specified with apply are cumulative. Actions may be specified in field classes and additional actions added in the 'has_field' declaration.

Moose types for constraints and transformations

Moose types can be used to do both constraints and transformations. If a coercion exists it will be applied, resulting in a transformation.

A Moose type: subtype 'MyStr' => as 'Str' => where { /^a/ };

This is a simple constraint checking if the value string starts with the letter 'a'.

Another Moose type: subtype 'MyInt' => as 'Int'; coerce 'MyInt' => from 'MyStr' => via { return $1 if /(\d+)/ };

This type contains a coercion.

You can use them in a field like this:

has_field 'some_text_to_int' => (
    apply => [ 'MyStr', 'MyInt' ]
);

This will check if the field contains a string starting with 'a' - and then coerce it to an integer by extracting the first continues string of digits.

If the error message returned by the Moose type is not suitable for displaying in a form, you can define a different error message:

apply => [ { type => 'MyStr', message => 'Not a valid value' } ];

Non-Moose checks and transforms

A simple 'check' constraint uses the 'check' keyword pointing to a coderef, a regular expression, or an array of valid values, plus a message.

A 'check' coderef will be passed the current value of the field. It should return true or false:

has_field 'this_num' => (
    apply => [
       {
           check => sub { if ( $_[0] =~ /(\d+)/ ) { return $1 > 10 } },
           message => 'Must contain number greater than 10',
       }
);

A 'check' regular expression:

has_field 'some_text' => (
    apply => [ { check => qr/aaa/, message => 'Must contain aaa' } ],
);

A 'check' array of valid values:

has_field 'more_text' => (
    aply => [ { check => ['aaa', 'bbb'], message => 'Must be aaa or bbb' } ]
);

A simple transformation uses the 'transform' keyword and a coderef. The coderef will be passed the current value of the field and should return a transformed value.

has_field 'sprintf_filter' => (
    apply => [ { transform => sub{ sprintf '<%.1g>', $_[0] } } ]
);

deflations

Use deflations to convert from an inflated database or internal value to a value suitable for displaying in an HTML form.

trim

A Hashref containing a transfrom 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 { } }

Trimming is performed before any other defined actions.

METHODS

new [parameters]

Create a new instance of a field. Initial values are passed as a list of parameters.

full_name

This returns the name of the field, but if the field is a child field will prepend the field with the parent's field name. For example, if a field is "month" and the parent's field name is "birthday" then this will return "birthday.month".

set_order

This sets the field's order to the form's field_counter and increments the counter. This may be used in a template when displaying the field.

add_error

Add an error to the list of errors. If $field->form is defined then process error message as Maketext input. See $form->language_handle for details. Returns undef.

return $field->add_error( 'bad data' ) if $bad;

process

This method does standard validation, which currently tests:

required        -- if field is required and value exists

Then if a value exists, calls the 'augment' validate_field method in subclasses.

If these tests pass, the field's validate method is called

$field->validate;

If $field->validate returns true then the input value is copied from the input attribute to the field's value attribute.

The field's error list and internal value are reset upon entry.

validate

This method validates the input data for the field and returns true if the data validates. An error message must be added to the field with $field->add_error( ... ) if the value does not validate. The default method is to return true.

sub validate {
    my $field = shift;
    my $input = $field->input;
    return $field->add_error( ... ) if ( ... );
    return 1;
}

test_ranges

If range_start and/or range_end is set AND the field does not have options will test that the value is within range. This is called after all other validation.

input_defined

Returns true if $self->input contains any non-blank input.

value_changed

Returns true if the value in the item has changed from what is currently in the field's value.

This only does a string compare (arrays are sorted and joined).

required_text

Returns "required" or "optional" based on the field's setting.

dump_field

A little debugging.

AUTHORS

Gerda Shank, gshank@cpan.org

Based on the original source code of Form::Processor::Field by Bill Moseley

COPYRIGHT

This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.