NAME

HTML::FormHandler::Intro - basic usage of FormHandler

SYNOPSIS

To use HTML::FormHandler, you need to create a form class, call the form class from a controller, and choose a method of displaying the form in an HTML page.

Create a Form, subclassed from HTML::FormHandler::Model::DBIC

package MyApp:Form::User;

use Moose;
extends 'HTML::FormHandler::Model::DBIC';

# Associate this form with a DBIx::Class result class
has '+item_class' => ( default => 'User' );

# Define the fields that this form will operate on
# Field names must be column or relationship names in your
# DBIx::Class result class
sub profile {                 # or: has '+profile' => ( default => ...)
    return {
        fields => {
            name        => {
               type => 'Text',
               label => 'Name:',
               required => 1,
               noupdate => 1,
            },
            age         => {
                type => 'PosInteger',
                label    => 'Age:',
                required => 1,
            },
            sex         => {
                type => 'Select',
                label => 'Gender:',
                required => 1,
            },
            birthdate   => '+MyApp::Field::Date', # customized field class
            hobbies     =>  {
                type => 'Multiple',
                size => 5,
            },
            address     => 'Text',
            city        => 'Text',
            state       => 'Select',
        },

        dependency => [
            ['address', 'city', 'state'],
        ],
    };

Then in your template for an input field:

<p>
[% f = form.field('address') %]
<label class="label" for="[% f.name %]">[% f.label || f.name %]</label>
<input type="text" name="[% f.name %]" id="[% f.name %]" value="[ f.fif %]">
</p>

The value can come from the hash returned by $form->fif, from the 'fif' attribute of the field, or can be supplied by FillInForm. Plain HTML works fine for a simple input field if you use FillInForm to supply the value:

For a select list, provide a relationship name as the field name, or provide an options_<field_name> subroutine in the form. FillInForm alone is not enough for select fields, since you need to access the field 'options'. (field attributes: sort_order, label_column, active_column). TT example:

<p>
[% f = form.field('sex') %]
<label class="label" for="[% f.name %]">[% f.label || f.name %]</label>
<select name="[% f.name %]">
  [% FOR option IN f.options %]
    <option value="[% option.value %]" [% IF option.value == f.fif %]selected="selected"[% END %]>[% option.label | html %]</option>
  [% END %] 
</select>
</p>

A multiple select list where 'hobbies' is a 'many_to_many' pseudo-relationship. (field attributes: sort_column, label_column, active_column).

  <p>
  [% f = form.field('hobbies') %]
  <label class="label" for="[% f.name %]">[% f.label || f.name %]</label>
  <select name="[% f.name %]" multiple="multiple" size="[% f.size %]">
    [% FOR option IN f.options %]
      <option value="[% option.value %]" [% FOREACH selval IN f.fif %][% IF selval == option.value %]selected="selected"[% END %][% END %]>[% option.label | html %]</option>
    [% END %] 
  </select>
  </p>

Then in a Catalyst controller (with Catalyst::Controller::HTML::FormHandler):

package MyApp::Controller::User;
use strict;
use warnings;
use base 'Catalyst::Controller::HTML::FormHandler';

# Create or edit
sub edit : Local {
    my ( $self, $c, $user_id ) = @_;
    $c->stash->{template} = 'user/edit.tt'; 
    # Validate and insert/update database. Args = pk, form name
    return unless $self->update_from_form( $user_id, 'User' );
    # Form validated.
    $c->stash->{user} = $c->stash->{form}->item;
    $c->res->redirect($c->uri_for('profile'));
}

With the Catalyst controller the schema is set from the model_name config options, ($c->model($model_name)...), but it can also be set by passing in the schema on "new", or setting with $form->schema($schema). If you want to use FillInForm to fill in values instead of the field's fif attribute, use Catalyst::Controller::HTML::FormHandler.

DESCRIPTION

HTML::FormHandler is a form handling class primarily useful for getting HMTL form data into the database. It provides attributes on fields that can be used for creating a set of widgets and highly automatic templates, but does not actually create the templates themselves.

The DBIC & CDBI models will save form fields automatically to the database, will retrieve selection lists from the database (with type => 'Select' and a fieldname containing a single relationship, or type => 'Multiple' and a many_to_many relationship), and will save the selected values (one value for 'Select', multiple values in a mapping table for a 'Multiple' field).

The 'form' is a Perl subclass of the model class, and in it you define your fields (with many possible attributes), and initialization and validation routines. Because it's a Perl class, you have a lot of flexibility.

You can define your own HTML::FormHandler::Field classes to create your own field types, and perform specialized validation. And you can subclass the methods in HTML::FormHandler::Model::DBIC and HTML::FormHandler.

The Catalyst::Controller::HTML::FormHandler package includes a working example using a SQLite database and a number of forms.

The Form

A "form" class is where fields and validation routines are defined. It is a subclass of a FormHandler model class (for database forms) or FormHandler itself (for non-database forms). Since it is a subclass, many aspects of FormHandler behavior can be changed in a particular form.

Form Models

If you are not using a database interface, the base class for your forms is HTML::FormHandler. For use with a database, you need to use a form model class-- a class that knows how to work with your data objects, such as HTML::FormHandler::Model::DBIC or HTML::FormHandler::Model::CDBI.

When using a database model, form field values for the row are retrieved from the database using the field names as database class accessors. FormHandler will use relationships to populate single and multiple selection lists, and validate input. It doesn't yet do anything with other relationships.

You can pass in either the primary key or a row object to the form. If a primary key is passed in, the model will use the item_class (DBIC source name) to fetch the row from the database. The database row is stored in the form's "item" attribute.

The $form->update_from_form method will validate the parameters and then update or create the database row object.

The form profile

Returns a hashref of field definitions.

The possible keys in the profile hashref are:

required
optional
fields
auto_required
auto_optional
dependency

The profile is the easiest way to define the fields in your form (though you can also add fields individually).

You can categorize your fields as required and optional with two separate hashrefs:

my $profile => {
    required => {
        field_one => 'Text', 
    },
    optional => {
        field_two => 'Text', 
    },
};

Or you can use one hashref and indicate 'required' as yet another field attribute:

my $profile => {
    fields => [
        field_one => {
           type => 'Text',
           required => 1
        },
        field_two => 'Text,
     ],
 }; 

(Making the value of the "fields" key an array allows FormHandler to create the "order" of the fields in the order in which you define them.) The only required key is "type", which determines the field class. All other keys are attributes of HTML::FormHandler::Field or its subclasses.

An example of a select field:

my $profile = {
    fields => {
        favorite_color => {
            type            => 'Select',
            label_column    => 'color_name',
            active_column   => 'is_active',
        },
    },
};

The definition above is the equivalent of the following code:

my $field = HTML::FormHandler::Field::Select->new(
   name => 'favorite_color', 
   required => 1,
   label_column => 'color_name',
   active_column => 'is_active' );
$form->add_field( $field );

For the "auto" profile keys, provide a list of field names. The field types will be determined by calling 'guess_field_type' in the model.

auto_required => ['name', 'age', 'sex', 'birthdate'],
auto_optional => ['hobbies', 'address', 'city', 'state'],

The 'guess_field_type' method could be customized to provide more sophisticated determination of types. See the model class.

The 'dependency' profile key is an array of arrays of field names. During validation, if any field in a given group contains the pattern /\S/ (non-blank), the 'required' flag is set for all of the fields in the group.

sub profile {
    return {
        fields => [
            name    => 'Text',
            age     => 'Integer',
            date    => 'DateTime',
            comment => 'Text',
            ...
        ],
        dependency => [
           ['address', 'city', 'state', 'zip'],
           ['cc_no', 'cc_expires'],
        ],
    };
}

Fields

A form's fields are created from the definitions in the "profile" subroutine. FormHandler processes the profile and creates an array of HTML::FormHandler::Field objects. The "type" of a field in the profile 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 can also be added dynamically with the 'add_field' method.

In the template the fields are accessed with form.field('name'). Field errors are in $field->errors.

Each form field is associated with a general type. The type name is used to load a module by that name:

my $profile = {
    required => {
        title   => 'Text',
        age     => 'Integer',
    },
};

Type "Text" loads the HTML::FormHandler::Field::Text module and type 'Integer' loads HTML::FormHandler::Field::Integer.

The fields are assumed to be in the HTML::FormHandler::Field name space. If you want to explicitly list the field's package prefix it with a plus sign. The field name space for "+" prefixed fields can be set with the form's "field_name_space" attribute:

has '+field_name_space' => ( default => 'MyApp::Form::Field' );

required => {
    name    => 'Text',  # HTML::FormHandler::Field::Text
    foo     => '+Foo',  # MyApp::Form::Field::Foo
},

The most basic type is "Text", which takes a single scalar value. A "Select" class is similar, but its value must be a valid choice from a list of options. A "Multiple" type is like "Select" but it allows selecting more than one value at a time.

Each field has a "value" method, which is the field's internal value. This is the value your database object would have (e.g. scalar, boolean 0 or 1, DateTime object). A field's internal value is converted to the external value by use of the field's format_value() method. This method returns a hash which allows a single internal value to be made up of multiple fields externally. For example, a DateTime object internally might be formatted as a day, month, and year externally.

When data is passed in to validate the form, it is trimmed of leading and trailing whitespace by the Field module and placed in the field's "input" attribute. Each field has a validate method that validates the input data and then moves it to the internal representation in the "value" attribute. Depending on the model, it's this internal value that is stored or used by your application.

By default, the validation is simply to copy the data from the "input" to the "value" field attribute, but you might have a field that must be converted from a text representation to an object (e.g. month, day, year to DateTime).

Other methods for your form

options_$fieldname

If you have a 'Select' or 'Multiple' field, there are two ways to provide the 'options', or the list of values and labels for the select list. 1) Get them from a database table (from the relationship that is the field name), or 2) provide them from an options_$fieldname method.

An 'options_$fieldname' method should return a list of ordered key (option value) and value (label to be displayed in the select list) pairs.

sub options_fruit {
    return (
        1   => 'apples',
        2   => 'oranges',
        3   => 'kiwi',
    );
}

You can also write custom methods to retrieve the option info from the database:

sub options_country
{
   my $self = shift; 
   my @rows =
      $self->schema->resultset( 'Country' )->
         search( {}, { order_by => ['rank', 'country_name'] } )->all;
   return [ map { $_->digraph, $_->country_name } @rows ];
}

init_value_$fieldname

Allows you to provide a different initial value for a particular field than that in the database.

sub init_value_license {
   my ( $self, $field, $item ) = @_;
   return 0 unless $item && $item->license_id; 
   return $item->license_id;
}

validate_$fieldname

Do per-field validation customization not handled by the Field class.

sub validate_age {
    my ( $self, $field ) = @_;
    $field->add_error('Sorry, you must be 18')
        if $field->value < 18;
}

cross_validate

Handle cross-field validation, or any validation that needs to be done after the entire form is validated. This method is executed whether or not the form has validated so far.

sub cross_validate {
   my $self = shift;
   if ( $self->field('count')->value && $self->field('duration')->value )
   {
       $self->field('duration')->add_error( 
                 'Do not enter both a count and a duration' );
   }
}

update_model

Override the model's 'update_model' method to do additional updates.

sub update_model {
   my $self = shift;
   $self->SUPER::update_model;
   my $event = $self->item;
   $event->update( ... );
}

Filling the HTML form with values

There are three ways to get the database or parameter values into the actual HTML form.

You can use the field method 'fif' (where "f" is "form.field('book')" ):

[% f.fif %]

You can use the hash returned by the form method "fif":

[% form.fif.book %]

Or you can use HTML::FillInForm and the $form->fif hash. For Catalyst, an example "end" routine to call FillInForm is provided in Catalyst::Controller::HTML::FormHandler

If you are already using FormHandler field attributes in your form elements, then using the field 'fif' method is probably easiest. If you are not using FormHandler field attributes, then your choice is between using form.fif and FillInForm.

If you are not using FormHandler select lists and you use FillInForm, then it is possible to have FormHandler process HTML forms that have no template references to the form object at all, as long as the field names are correct. If you think that FillInForm is evil, then you could manage with only using FormHandler to fill in the form.

AUTHORS

Gerda Shank, gshank@cpan.org

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