/ 
Catalyst-Plugin-Form-Processor-0.05
River stage zero No dependents
/ Catalyst::Plugin::Form::Processor

NAME

Catalyst::Plugin::Form::Processor - Use Form::Processor with Catalyst

SYNOPSIS

In the Catalyst application base class:

use Catalyst qw/ Form::Processor /;

__PACKAGE__->config->{form} = {
    no_fillin       => 1,  # Don't auto-fill forms with HTML::FillInForm
    pre_load_forms  => 1,  # Try and load forms at setup time
    form_name_space => 'My::Forms',
    debug           => 1,   # Show forms pre-loaded.
};

Then in a controller:

package App::Controller::User;
use strict;
use warnings;
use base 'Catalyst::Controller';

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

    # Validate and insert/update database
    reutrn unless $c->update_from_form( $user_id );

    # Form validated.

    $c->stash->{first_name} = $c->stash->{form}->value( 'first_name' );
}

# Form that doesn't update database
sub profile : Local {
    my ( $self, $c ) = @_;

    # Redisplay form
    reutrn unless $c->validate_form;

    # Form validated.

    $c->stash->{first_name} = $c->stash->{form}->value( 'first_name' );
}


# Use HTML::FillInForm to populate a form:
$c->stash->{fillinform} = $c->req->parameters;

DESCRIPTION

If not obvious from the SYNOPSIS above, this plugin adds methods to make Form::Processor easy to use with Catalyst. The plugin uses the current action name to find the form module, creates the form object and stuffs it into the stash, and passes the Catalyst request parameters to the form for validation. What else could you want?

Perhaps you want automatic HTML form generation? No, this module does not do that. When was the last time you wrote a web application where automatically generated forms would be close to acceptable? Forms always need customization and error message formatting, custom javascript, etc.

That said, check out the included example Catalyst application to see how easy it is to place fields and error messages on a page. Adding new forms often is as simple a listing the fields to include on the page.

The method $c->update_from_form is used when the form inherits from a Form::Processor model class (e.g. Form::Processor::Model::CDBI) which will load a form's current values from a database and update/create rows in the database from a posted form.

$c->validate_form simply validates the form and you must then decide what to do with the validated data. This is useful when the posted data will be used for something other than updating a row in a database.

The $c->form method will automatically load a form module from disk. Both $c->update_from_form and $c->validate_form call this method to load the form for you. So, you generally don't need to call this directly.

Forms are assumed to be in the $App::Form name space. But, that's just the default. In case you are unfamiliar with Form::Processor, forms are Perl modules that define not only the fields associated with a form but also any extra validation (and cross validation) you may need to process a form.

The form object is stored in the stash as $c->stash->{form}. Templates can use this to access for form.

In addition, this Plugin use HTML-FillInForm to populate the form. Typically, this data will come automatically form the current values in the form object, but can be overridden by populating the stash with a hash reference:

$c->stash->{fillinform} = $c->req->parameters;

Note that this can also be used to populate forms not managed by Form::Processor. Currently, only one form per page is supported.

Form::Processor (currently) does not generate HTML. This distribution contains a sample Catalyst application that includes an overly complex Template Toolkit file (form_widgets.tt) for generating HTML. The application can be found in the t/example directory of the distribution.

METHODS

form ( $item_or_args_ref, $form_name );

$form = $c->form;
$form = $c->form( $user_id );
$form = $c->form( $args_ref );
$form = $c->form( $args_ref, $form_name );

Generates a form object, populates the stash "form" and returns the form object. This method is typically not used. Use update_from_form or validate_form instead.

The form will be require()ed at run time so the form does not need to be explicitly loaded by your application. The form is expected to be in the App::Form name space, but that can be overridden.

But, it might be worth loading the modules at compile time if you have a lot of modules to save on memory (e.g. under mod_perl). See "pre_load_forms" below.

The Catalyst context ($c) is made available to the form via the form's user data attribute. In the form you may do:

my $c = $form->user_data->{context};

Pass: $item_or_args_ref. This can be scalar: it will be assumed to be the id of the row to edit hash ref: assumed to be a list of options and will be passed as a list to Form::Processor->new. object: and will be set as the item and item_id is set by calling the "id" method on this object. If id is not the correct method then pass a hash reference instead.

If $form_name is not provided then will use the current controller
class and the action for the form name.  If $form_name is defined then
it is appended to C<$App::Form::>.  A plus sign can be included
to avoid prefixing the form name.


package MyApp::Controller::Foo::Bar
sub edit : Local {

    # MyAPP::Form::Foo::Bar::Edit->new
    # Note the upper case -- ucfirst is used
    my $form = $c->form;

    # MyAPP::Form::Login::User->new
    my $form = $c->form( $args_ref, 'Login::User' );

    # External form Other::Form->new
    my $form = $c->form( $args_ref, '+Other::Form' );

Returns: Sets $c->{form} by calling new on the form object. That value is also returned.

validate_form

return unless $c->validate_form;

This method passes the request parameters to the form's validate method and returns true if all fields validate.

This is the method to use if you are not using a Form::Processor::Model class to automatically update or insert a row into the database.

update_from_form

This combines common actions on CRUD tables. It replaces, say:

my $form = $c->form( $item );

return unless $c->form_posted
    && $form->update_from_form( $c->req->parameters );

with

$c->update_from_form( $item )

For this to work your form should inherit from a Form::Processor::Model class (e.g. see Form::Processor::Model::CDBI), or your form must have an update_from_form() method (which calls validate).

form_posted

This returns true if the request was a post request. This could be replace with a method that does more extensive checking, such as validating a form token to prevent double-posting of forms.

EXTENDED METHODS

dispatch

Automatically fills in a form if $form variable is found. This can be disabled by setting

$c->config->{form}{no_fillin};

setup

If the pre_load_forms configuration options is set will search for forms in the name space provided by the form_name_space configuration list or by default the application name space with the suffix ::Form appended (e.g. MyApp::Form).

CONFIGURATION

Configuration is specified within MyApp->config->{form}}. The following options are available:

no_fillin

Don't use use HTML::FillInForm to populate the form data.

pre_load_forms

It this is true then will pre-load all modules in the MyApp::Form name space during setup. This works by requiring the form module and loading associated form fields. The form is not initialized so any fields dynamically loaded may not be included.

This is useful in a persistent environments like mod_perl or FastCGI.

form_name_space

This is a list of name spaces where to look for forms to pre load. It defaults to the application name with the ::Form suffix (e.g. MyApp::Form). Note, this DOES NOT currently change where $c->form looks for form modules. Not quite sure why that's not implemented yet.

debug

If true will write brief debugging information when running setup.

AUTHOR

Bill Moseley

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See also

Form::Processor

Form::Processor::Model::CDBI