view release on metacpan or  search on metacpan

lib/HTML/FormHandler/Manual/Intro.pod  view on Meta::CPAN

it you define your fields and validation routines. Because it's a Perl class
written in Moose, you have a lot of flexibility and control.

You can validate with Perl methods or Moose type constraints; you can use
your own validation libraries. You can define your own field classes that
perform specialized validation.

When the form is validated, you can get the validated values back with
C<< $form->value >>.

A working example of a Catalyst app using FormHandler forms is available
on github at L<https://github.com/gshank/formhandler-example>.

=head1 Basics

=head2 Create a form class

The most common way of using FormHandler is to create a form package. You
must 'use' "HTML::FormHandler::Moose" and 'extend' FormHandler:

    package MyApp::Form::Sample;
    use HTML::FormHandler::Moose;
    extends 'HTML::FormHandler';

Then you add some fields with 'has_field', and a field 'type' (the short
name of the field package). (Fields with no type have type 'Text'.)

    has_field 'foo';
    has_field 'bar' => ( type => 'Select' );

Basic field types are Text, Select, Checkbox, Submit, Hidden, Reset,
TextArea, Password, Upload. See L<HTML::FormHandler::Manual::Fields> for
more information.

=head2 Or create a form class dynamically

You can also create a form class 'dynamically', by creating a 'new'
HTML::FormHandler object. Use a 'field_list' parameter to create the fields
instead of 'has_field'.

    my $form = HTML::FormHandler->new( field_list => [
            'username' => { type => 'Text' },
            'selections' => { type => 'Select' },
        ]
    );

Some features will not be available using this method (like the automatic
use of 'validate_<field_name>' methods) and it's not as easy to test,
of course.

=head2 Process the form

The form's 'process' method should be run on each request, passing in the
request parameters:

    $form->process( params => $c->request->body_parameters,
        action => $action,
    );

If the parameters are not empty, then validation will be performed. The
corollary is that you should not pass in extra parameters when the form
has not been posted. A special 'posted' flag can be used if
the form consists entirely of fields like checkboxes that do not include
names in params if unchecked, and also works to prevent validation from
being performed if there are extra params:

    $form->process( posted => ( $c->req->method eq 'POST' ),
        params => $c->request->parameters, action => $action );

There is an alternative method for processing the form, which is sometimes
preferred for persistent forms. It returns a 'result' object, and clears
the form:

    my $result = $form->run( params => $c->request->body_parameters );

You can also set most other FormHandler attributes on the 'process' call.,
One useful feature is that you can activate or inactivate fields:

    $form->process( params => $params, active => ['field1', 'field2'] );

See also L<HTML::FormHandler>.

=head2 Or process a database form

A database form inherits from L<HTML::FormHandler::Model::DBIC> instead of
L<HTML::FormHandler>. You must either pass in the DBIC row object or give
FormHandler information to retrieve the row object.

    $form->process( item => $row, params => $params );
    -- or --
    $form->process( item_id => $id, schema => $schema,
        item_class => 'MyRow', params => $params );

'item_class' is often set in the form class.

See also L<HTML::FormHandler::Manual::Database> and
L<HTML::FormHandler::TraitFor::Model::DBIC>.

=head2 After processing the form

A database form will have saved the data or created a new row, so often no
more processing is necessary. You can get the structured field values from
C<< $form->value >>, and do whatever you want with them.

If the validation succeeded, you may want to redirect:

    $form->process( params => $params );
    return unless $form->validated
    $c->res->redirect( .... );
    -- or --
    return unless $form->process( params => params );
    $c->res->redirect;

=head2 Rendering the form

At its simplest, all you need to do is C<< $form->render >> in a
template.

    [% form.render %]

The automatic rendering is powerful and flexible -- you can do almost