=head1 NAME
HTML::FormHandler::Manual
=head1 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:
[% f = form.field('address') %]
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_ 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:
[% f = form.field('sex') %]
A multiple select list where 'hobbies' is a 'many_to_many' pseudo-relationship.
(field attributes: sort_column, label_column, active_column).
[% f = form.field('hobbies') %]
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 L.
=head1 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 L 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 L package includes a working
example using a SQLite database and a number of forms.
=head2 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.
=head2 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
L or L.
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.
=item The profile in your form
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 L or its subclasses.
An example of a select field:
my $profile = {
required => {
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 => 'DateTimeDMYHM',
comment => 'Text',
...
],
dependency => [
['address', 'city', 'state', 'zip'],
['cc_no', 'cc_expires'],
],
};
}
=head2 Fields
A form's fields are created from the definitions in the "profile" subroutine.
FormHandler processes the profile and creates an array of
L 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 C 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).
=head1 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 L and the $form->fif hash. For Catalyst,
an example "end" routine to call FillInForm is provided in
L
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.
=head1 AUTHORS
Gerda Shank, gshank@cpan.org
=head1 COPYRIGHT
This library is free software, you can redistribute it and/or modify it under
the same terms as Perl itself.
=cut