NAME

Catalyst::Model::HTMLFormhandler - Proxy a directory of HTML::Formhandler forms

SYNOPSIS

    package MyApp::Model::Form;

    use Moose;
    extends 'Catalyst::Model::HTMLFormhandler';

    __PACKAGE__->config( form_namespace=>'MyApp::Form' );

And then using it in a controller:

    my $form = $c->model("Form::Email");  # Maps to MyApp::Email via MyApp:Model::Email

    # If the request is a POST, we process parameters automatically
    if($form->is_valid) {
      ...
    } else {
      ...
    }

DESCRIPTION

Assuming a project namespace 'MyApp::Form' with HTML::Formhandler forms. like the following example:

  package MyApp::Form::Email;

  use HTML::FormHandler::Moose;

  extends 'HTML::FormHandler';

  has aaa => (is=>'ro', required=>1);
  has bbb => (is=>'ro', required=>1);

  has_field 'email' => (
    type=>'Email',
    size => 96,
    required => 1);

You create a single Catalyst model like this:

    package MyApp::Model::Form;

    use Moose;
    extends 'Catalyst::Model::HTMLFormhandler';

    __PACKAGE__->config( form_namespace=>'MyApp::Form' );

(Setting 'form_namespace' is optional, it defaults to the application namespace plus "::Form" (in this example case that would be "MyApp::Form").

When you start your application it will register one model for each form in the declared namespace. So in the above example you should see a model 'MyApp::Model::Form::Email'. This is a 'PerRequest' model since it does ACCEPT_CONTEXT, it will generate a new instance of the form object once per request scope.

It will also create one model with the ::IsValid suffix, which is a shortcut to return a form only if its valid and undef otherwise.

You can set model configuration in the normal way, in your application general configuration:

    package MyApp;
    use Catalyst;

    MyApp->config(
      'Model::Form::Email' => { aaa => 1000 }
    );
    
    MyApp->setup;

And you can pass additional args to the 'new' call of the form when you request the form model:

     my $email = $c->model('Form::Email', bbb=>2000);

Additional args should be in the form of a hash, as in the above example OR you can pass a single argument which is either an object, hashref or id followed by a hash of remaining arguements. These first argument gets set to the item or item_id since its common to need:

    my $email = $c->model('Form::Email', $dbic_email_row, %args);

Or if its a HashRef, these are set to the params for processing.

The generated proxy will also add the ctx argument based on the current value of $c, although using this may not be a good way to build well, decoupled applications. It also will add the schema argument if you set a schema_model_name.

We offer two additional bit of useful suger:

If you pass argument 'action_from' with a value of an action object or an action private name that will set the form action value. If 'action_from' is an arrayref we dereference it when building the url.

By default if the request is a POST, we will process the request arguments and return a form object that you can test for validity. If you don't want this behavior you can disable it by passing 'no_auto_process'. For example:

    my $form = $c->model("Form::XXX", no_auto_process=>1)

ATTRIBUTES

This class defines the following attributes you may set via standard Catalyst configuration.

form_namespace

This is the target namespace that Module::Pluggable uses to look for forms. It defaults to 'MyApp::Form' (where 'MyApp' is you application namespace).

schema_model_name

The name of your DBIC Schema model (if you have one). If you set this, we will automatically instantiate your form classes with as schema => $model argument. Useful if you are using HTML::FormHandler::Model::DBIC.

roles

A list of Moose::Roles that get applied automatically to each form model.

post_method

This is the name of the method called on Catalyst::Request used to access any POSTed data. Required field, the options are 'body_data' and 'body_parameters. The default is 'body_data'.

no_auto_process

By default when createing the perrequest form if the request is a POST we just go ahead and process those args. Setting this to true will disable this behavior globally if you prefer more control.

SPECIAL ARGUMENTS

You may pass the following special arguments to $c->model("Form::XXX") to influence how the form object is setup.

no_auto_process

Turns off the call to ->process when the request is a POST.

action_from

Shortcut to create the action value of the form. If an object, we set 'action' from $c->uri_for($object). If its an arrayref from $c->uri_for( @$action_from).

ACTION ATTRIBUTES.

FormModelTarget( $model)

When used on an action, sets that action as the target of the form action. This is a bit experimental. We get any needed captures and arguments from the current request, this this only works if the target action has the same number of needed args and captures.

AUTHOR

John Napiorkowski email:jjnapiork@cpan.org

SEE ALSO

Catalyst, Catalyst::Model, HTML::Formhandler, Module::Pluggable

COPYRIGHT & LICENSE

Copyright 2015, John Napiorkowski email:jjnapiork@cpan.org

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

cpanm Catalyst::Model::HTMLFormhandler

perl -MCPAN -e shell
install Catalyst::Model::HTMLFormhandler