# 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](https://metacpan.org/pod/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](https://metacpan.org/pod/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.

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.

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.

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.

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](https://metacpan.org/pod/Catalyst) configuration.

## form\_namespace

This is the target namespace that [Module::Pluggable](https://metacpan.org/pod/Module::Pluggable) uses to look for forms.
It defaults to 'MyApp::Form' (where 'MyApp' is you application namespace).

## roles

A list of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get applied automatically to each form model.

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

# AUTHOR

John Napiorkowski [email:jjnapiork@cpan.org](email:jjnapiork@cpan.org)

# SEE ALSO

[Catalyst](https://metacpan.org/pod/Catalyst), [Catalyst::Model](https://metacpan.org/pod/Catalyst::Model), [HTML::Formhandler](https://metacpan.org/pod/HTML::Formhandler), [Module::Pluggable](https://metacpan.org/pod/Module::Pluggable)

# COPYRIGHT & LICENSE

Copyright 2015, John Napiorkowski [email:jjnapiork@cpan.org](email:jjnapiork@cpan.org)

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