NAME
Catalyst::Plugin::Form::Processor - methods for processing forms with Form::Processor
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' );
}DESCRIPTION
This plugin adds methods to make using Form::Processor easy to use with Catalyst. The $c->form method will automatically load a form module from disk based. Forms are assumed to be in the $App::Form name space. Typically, $c->form is not called directly, rather $c->update_from_form or $c->validate_form is used instead.
$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 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.
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. 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.
The form will be require()ed at run time so the form does not need to be specifically required. The form is expected to be in the App::Form name space.
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. 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. an 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 paramters 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 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 load. It defaults to the application name with the ::Form suffix (e.g. MyApp::Form). Note, this DOES NOT currently change where
$c->formlooks for form modules. - 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.