The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Catalyst-Plugin-Form-Processor-1.140270
River stage zero No dependents
++
/ Catalyst::Plugin::Form::Processor

NAME

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

VERSION

version 1.140270

SYNOPSIS

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;

DESCRIPTION

"This distribution should not exist" - https://rt.cpan.org/Ticket/Display.html?id=40733

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.

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.

finalize

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

EXTENDED METHODS

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.

model_name

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.

debug

If true will write brief debugging information when running setup.

See also

Form::Processor

Form::Processor::Model::CDBI

AUTHOR

Bill Moseley <mods@hank.org>

COPYRIGHT AND LICENSE

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.