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


version 1.140270


In the Catalyst application base class:

    use Catalyst;

    with 'Catalyst::Plugin::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.
        schema_class    => 'MyApp::DB',

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
        return 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
        return 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;


"This distribution should not exist" -

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.

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 create an instance of your form class. 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. This can be overridden with the form_name_space option.

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 ( $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.


    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.


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 );


    $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).


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.


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



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 is specified within MyApp->config->{form}}. The following options are available:


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


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.


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.


Defines the default model class. To play nicely with Form::Processor::Model::DBIC will set "schema" option when creating a new Form if this value is set.

Basically does:

    $schema = $c->model( $model_name )->schema;

Can be overridden by a stash element of the same name.


If true will write brief debugging information when running setup.

See also




Bill Moseley <>


This software is copyright (c) 2012 by iParadigms, LLC..

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