=head1 NAME

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

=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:

   <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.value %]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.value %][% 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 L<Catalyst::Controller::HTML::FormHandler::FifEnd>.


=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<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 L<Catalyst::Controller::HTML::FormHandler> package includes a working 
example using a SQLite database and a number of forms. 

=head1 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.

=head1 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<HTML::FormHandler::Model::DBIC> or L<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.  

=head1 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 L<HTML::FormHandler::Field> 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'],
            ],
        };
    }

=head1 Fields

A form's fields are created from the definitions in the "profile" subroutine.
FormHandler processes the profile and creates an array of 
L<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 C<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).

=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<HTML::FillInForm> and the $form->fif hash. For Catalyst, 
an example "end" routine to call FillInForm is provided in
L<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.

=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
