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 routine by overriding 'validate_field'.

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.

input

Input value for the field, usually from a parameter hash, but could also be set with an accessor. Validation is performed on the 'input' attributes. A change in this attribute triggers setting 'fif'.

fif

For filling in forms. Input or value.

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.

sub_form

The field is made up of a sub-form.

A single field can be represented by multiple sub-fields contained in a form. This is a reference to that form.

form

A reference to the containing form.

prename

Field name prefixed by the form name and a dot. A field named "street" in a form named "address" would have a prename of "address.street". Use with the form attribute "html_prefix". 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

value_sprintf

This is a sprintf format string that is used when moving the field's input data to the field's value attribute. By defult this is undefined, but can be set in fields to alter the way the input_to_value() method formates input data.

For example in a field that represents money the field could define:

    has '+value_sprintf' => ( default => '%.2f' );

The field's 'value' will be formatted with two decimal places.

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.

validate_meth

Specify the form method to be used to validate this field.

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;

validate_field

This method does standard validation, which currently tests:

    required        -- if field is required and value exists

Then if a value exists:

    test_multiple   -- looks for multiple params passed in when not allowed
    test_options    -- tests if the params passed in are valid options

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 by calling:

    $field->input_to_value;

The default method simply copies the value. This method is only called if the field does not have any errors.

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

input_to_value

This method moves the 'input' attribute value to the 'value' attribute if 'value' is undefined (has not already been set in 'validate'). It calls the 'value_sprintf' routine to format the value before moving it.

Override this method if you want to convert the input to another format before saving in 'value'.

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.

trim_value

Trims leading and trailing white space for single parameters. If the parameter is an array ref then each value is trimmed.

Pass in the value to trim and returns value back

test_multiple

Returns false if the field is a multiple field and the input for the field is a list.

has_input

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

test_options

If the field has an "options" method then the input value (or values if an array ref) is tested to make sure they all are valid options.

Returns true or false

fif_value

A field class can use this method to format an internal value into hash for form parameters.

A Date field subclass might expand the value into:

    my $name = $field->name;
    return (
        $name . 'd'  => $day,
        $name . 'm' => $month,
        $name . 'y' => $year,
    );

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.

cpanm HTML::FormHandler

perl -MCPAN -e shell
install HTML::FormHandler