/ 
HTML-FormHandler-0.10
River stage two • 21 direct dependents • 31 total dependents
/ HTML::FormHandler::Manual::Intro

NAME

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

SUMMARY

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, although there is an example of a rendering role.

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 HTML::FormHandler for non-database forms, or a subclass of a model class for database forms, 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 HTML::FormHandler package includes a working example using a SQLite database and a number of forms in the test directory. You can execute the sample from a downloaded distribution package with:

perl -Ilib t/script/bookdb_server.pl

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 HTML::FormHandler::Moose;
extends 'HTML::FormHandler::Model::DBIC';

# Associate this form with a DBIx::Class result class
# Or 'item_class' can be passed in on 'new', or you
# you can always pass in a row object
has '+item_class' => ( default => 'User' );

# Define the fields that this form will operate on
# Field names are usually column, accessor, or relationship names in your
# DBIx::Class result class. You can also have fields that don't exist
# in your result class.

has_field 'name'    => ( type => 'Text', label => 'Username, required => 1,
   required_message => 'You must enter a username', unique => 1,
   unique_message => 'That username is already taken' );
# the css_class, title, and widget attributes are for use in templates
has_field 'age'     => ( type => 'PosInteger', required => 1, css_class => 'box',
   title => 'User age in years', widget => 'age_text', range_start => 18 ); 
has_field 'sex'     => ( type => 'Select', label => 'Gender', required => 1 );
# a customized field class
has_field 'birthdate => ( type => '+MyApp::Field::Date' );
has_field 'hobbies' => ( type => 'Multiple', size => 5 );
has_field 'address' => ( type => 'Text' );
has_field 'city'    => ( type => 'Text' );
has_field 'state'   => ( type => 'Select' );

has '+dependency' => ( default => sub {
        [
            ['address', 'city', 'state'],
        ],
    }
);

In a template, for an input field:

<p>
[% f = form.field('address') %]
<label class="label" for="[% f.name %]">[% f.label %]:</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 %]</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>

If you always use the same model for your forms, and the same form name space, you can specify the config values in your application module:

__PACKAGE__->config( { 'Controller::HTML::FormHandler' =>
    { model_name => 'DB', form_name_space => 'MyApp::Form' }} );

In a Catalyst controller:

package MyApp::Controller::User;
use Moose;
use base 'Catalyst::Controller';
has 'form' => ( isa => 'MyApp::Form::User', is => 'rw',
    default => sub { MyApp::Form::User->new } );

# Create or edit
sub edit : Local {
    my ( $self, $c, $user_id ) = @_;

    $c->stash( template => 'user/edit.tt' ); 
    return unless $self->form->process( item_id => $user_id,
       schema => $c->model('DB::User')->schema );

    # Form validated.
    $c->stash( user => $form->item );
    $c->res->redirect($c->uri_for('profile'));
}
...

With the DBIC model the schema is set from the 'item' (row object) passed in, or from the primary key ('item_id') and schema.

The example above uses persistent forms in a Moose attribute. The 'process' method will clear out non-persistent form values and update the information from the database row (if given). If you modify form attributes that are not automatically cleared, you must set those attributes on every request or clear them yourself.

You can also create a new form on each request with new:

my $form = BookDB::Form::Book->new( item => $book );
return unless $form->process( params => $c->req->parameters );

If you want to use FillInForm to fill in values instead of the field's fif attribute, you will need to set that up yourself in an 'end' routine or a finalize method. One option would be to set the 'fif' hash in a stash variable:

   my $validated = $self->form->process( ... );
   $c->stash( fillinform => $self->form->fif );
   return unless $validated;

and then check for the stash variable in your end routine and call FillInForm:

sub end : Private
{
   my ( $self, $c ) = @_;
   $c->forward('render') unless $c->res->output;
   if ($c->stash->{fillinform})
   {
      $c->response->body(
         HTML::FillInForm->new->fill(
            scalarref => \$c->response->{body},
            fdat      => $c->stash->{fillinform},
         )
      );
   }
}
sub render : ActionClass('RenderView') { }

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, use a model base 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, although it will return a hash of the relationship.

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->process or $form->update methods will validate the parameters and then update or create the database row object.

The form field_list

Returns a hashref of field definitions.

The possible keys in the field_list hashref are:

required
optional
fields
auto_required
auto_optional

The field_list one 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 $field_list => {
    required => {
        field_one => 'Text', 
    },
    optional => {
        field_two => 'Text', 
    },
};

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

my $field_list => {
    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 $field_list = {
    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" field_list 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.

Fields

A form's fields are created from the 'has_field' and 'field_list' definitions. FormHandler processes the field lists and creates an array of HTML::FormHandler::Field objects. The "type" of a field 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.

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' );

has_field 'name' => ( type => 'Text' ); # HTML::FormHandler::Field::Text
has_field 'foo'  => ( type => +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 fif_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 base field class 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).

Common form attributes

The 'dependency' field_list 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.

has '+dependency' => ( default => sub {
         [
            ['address', 'city', 'state', 'zip'],
            ['cc_no', 'cc_expires'],
         ],
     },
 );

The 'item_class':

has '+item_class' => ( default => 'Book' );

The form name:

has '+name' => ( default => 'book_form' );

The field name space for use with '+' prefixed fields:

has '+field_name_space' => ( default => 'MyApp::Form::Field' );
...
has_field 'subname' => ( type => '+SubName' );

An 'init_object' for filling in the form with default values instead of the database object. (To set individual field values use "init_value_$fieldname".)

has '+init_object' => ( default => sub { 
      {  name => 'Choose name',
         project => 'Standard'
      }
   }
);

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.

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.