.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "HTML::FormHandler::Manual::Catalyst 3pm"
.TH HTML::FormHandler::Manual::Catalyst 3pm "2017-11-11" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTML::FormHandler::Manual::Catalyst \- using HFH forms in Catalyst
.SH "VERSION"
.IX Header "VERSION"
version 0.40068
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Manual Index
.PP
This part of the FormHandler Manual describes the use of the HTML::FormHandler
package in Catalyst controllers.
.PP
See the other FormHandler documentation at HTML::FormHandler::Manual, or
the base class at HTML::FormHandler.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Although HTML::FormHandler can be used in any Perl web application, module, or
script, one of its most common uses is in Catalyst applications.
.PP
Using a form takes only a few lines of code, so it's not necessary to have
a Catalyst base controller, although you could make a base controller for
FormHandler if you're doing more than the basics.
.SS "A Controller Example"
.IX Subsection "A Controller Example"
The following example uses chained dispatching. The 'form' method is called
by both the create and edit actions.
.PP
.Vb 1
\&   package BookDB::Controller::Borrower;
\&
\&   use Moose;
\&   BEGIN { extends \*(AqCatalyst::Controller\*(Aq }
\&
\&   use BookDB::Form::Borrower;
\&
\&   sub borrower_base : Chained PathPart(\*(Aqborrower\*(Aq) CaptureArgs(0) { }
\&
\&   sub list : Chained(\*(Aqborrower_base\*(Aq) PathPart(\*(Aqlist\*(Aq) Args(0) {
\&      my ( $self, $c ) = @_;
\&      my $borrowers = [ $c\->model(\*(AqDB::Borrower\*(Aq)\->all ];
\&      my @columns = ( \*(Aqname\*(Aq, \*(Aqemail\*(Aq );
\&      $c\->stash( borrowers => $borrowers, columns => \e@columns,
\&                 template => \*(Aqborrower/list.tt\*(Aq );
\&   }
\&
\&   sub add : Chained(\*(Aqborrower_base\*(Aq) PathPart(\*(Aqadd\*(Aq) Args(0) {
\&      my ( $self, $c ) = @_;
\&      # Create the empty borrower row for the form
\&      $c\->stash( borrower => $c\->model(\*(AqDB::Borrower\*(Aq)\->new_result({}) );
\&      return $self\->form($c);
\&   }
\&
\&   sub item : Chained(\*(Aqborrower_base\*(Aq) PathPart(\*(Aq\*(Aq) CaptureArgs(1) {
\&      my ( $self, $c, $borrower_id ) = @_;
\&      $c\->stash( borrower => $c\->model(\*(AqDB::Borrower\*(Aq)\->find($borrower_id) );
\&   }
\&
\&   sub edit : Chained(\*(Aqitem\*(Aq) PathPart(\*(Aqedit\*(Aq) Args(0) {
\&      my ( $self, $c ) = @_;
\&      return $self\->form($c);
\&   }
\&
\&   sub form {
\&      my ( $self, $c ) = @_;
\&
\&      my $form = BookDB::Form::Borrower\->new;
\&      $c\->stash( form => $form, template => \*(Aqborrower/form.tt\*(Aq );
\&      return unless $form\->process( item => $c\->stash\->{borrower},
\&         params => $c\->req\->parameters );
\&      $c\->res\->redirect( $c\->uri_for($self\->action_for(\*(Aqlist\*(Aq)) );
\&   }
\&
\&   sub delete : Chained(\*(Aqitem\*(Aq) PathPart(\*(Aqdelete\*(Aq) Args(0) {
\&      my ( $self, $c ) = @_;
\&
\&      $c\->stash\->{borrower}\->delete;
\&      $c\->res\->redirect( $c\->uri_for($c\->action_for(\*(Aqlist\*(Aq)) );
\&   }
\&
\&   1;
.Ve
.SS "Another way to set up your form"
.IX Subsection "Another way to set up your form"
If you are setting the schema or other form attributes (such as the user_id,
or other attributes) on your form you could create a base controller that would set
these in the form on each call using Catalyst::Component::InstancePerContext,
or set them in a base Chained method.
.PP
.Vb 8
\&   sub book_base : Chained PathPart(\*(Aqbook\*(Aq) CaptureArgs(0) {
\&      my ( $self, $c ) = @_;
\&      my $form = MyApp::Form\->new;
\&      $form\->schema( $c\->model(\*(AqDB\*(Aq)\->schema );
\&      $form\->params( $c\->req\->parameters );
\&      $form\->user_id( $c\->user\->id );
\&      $c\->stash( form => $form );
\&   }
.Ve
.PP
Then you could just pass in the item_id when the form is processed.
.PP
.Vb 1
\&   return unless $c\->stash\->{form}\->process( item_id => $id );
.Ve
.SS "Putting a form in a Moose attribute"
.IX Subsection "Putting a form in a Moose attribute"
You can also put your form in a Moose attribute in the controller.
.PP
.Vb 6
\&    package MyApp::Controller::Book;
\&    use Moose;
\&    BEGIN { extends \*(AqCatalyst::Controller\*(Aq; }
\&    use MyApp::Form::Book;
\&    has \*(Aqedit_form\*(Aq => ( isa => \*(AqMyApp::Form::Book\*(Aq, is => \*(Aqrw\*(Aq,
\&       lazy => 1, default => sub { MyApp::Form::Book\->new } );
.Ve
.PP
Then you can process the form in your actions with
\&\f(CW\*(C`$self\->edit_form\->process( params => $c\->req\->body_parameters );\*(C'\fR or
\&\f(CW\*(C`my $result = $self\->edit_form\->run( params => $c\->req\->body_parameters );\*(C'\fR.
.SS "Using  HTML::FillInForm"
.IX Subsection "Using HTML::FillInForm"
If you want to use HTML::FillInForm to fill in values instead of
doing it in directly in a template using either the field or the form 'fif'
methods, you can use Catalyst::View::FillInForm on your view class:
.PP
.Vb 5
\&    package MyApp::View::TT;
\&    use Moose;
\&    with \*(AqCatalyst::View::FillInForm\*(Aq;
\&    ....
\&    1;
.Ve
.PP
and set the 'fif' hash in the 'fillinform' stash variable:
.PP
.Vb 3
\&    $self\->form\->process( ... );
\&    $c\->stash( fillinform => $self\->form\->fif );
\&    return unless $form\->validated;
.Ve
.PP
When the 'fillinform' stash variable is set, HTML::FillInForm will automatically
be used by your view to fill in the form values. This can be very helpful
when you want to build your forms by hand, or when you have legacy forms that
you're just trying to hook up to FormHandler.
.SS "The Catalyst context"
.IX Subsection "The Catalyst context"
FormHandler has a 'ctx' attribute that can be used to set the Catalyst context (or
anything you want, really). But if you can avoid passing in the context, you should do so,
because you're mixing up your \s-1MVC\s0 and it makes it much more difficult to test your
forms. But if you need to do it, you can:
.PP
.Vb 1
\&    my $form = MyApp::Form\->new( ctx => $c );
.Ve
.PP
Usually you should prefer to add new attributes to your form:
.PP
.Vb 3
\&    package MyApp::Form;
\&    use HTML::FormHandler::Moose;
\&    extends \*(AqHTML::FormHandler\*(Aq;
\&
\&    has \*(Aquser_id\*(Aq => ( is => \*(Aqrw\*(Aq );
\&    has \*(Aqhostname\*(Aq => ( is => \*(Aqrw\*(Aq );
\&    has \*(Aqcaptcha_store\*(Aq => ( is => \*(Aqrw\*(Aq );
\&    ....
\&    1;
.Ve
.PP
Then just pass the attributes in on new:
.PP
.Vb 2
\&    my $form => MyApp::Form\->new( user_id => $c\->user\->id, hostname => $c\->req\->host,
\&        captcha_store => $c\->{session}\->{captcha} );
.Ve
.PP
Or set them using accessors:
.PP
.Vb 3
\&    $form\->user_id( $c\->user\->id );
\&    $form\->hostname( $c\->req\->host );
\&    $form\->captcha_store( $c\->{session}\->{captcha} );
.Ve
.PP
Then you can access these attributes in your form validation methods:
.PP
.Vb 7
\&    sub validate_selection {
\&       my ( $self, $field ) = @_;
\&       if( $field\->value eq \*(Aqsomething\*(Aq && $self\->hostname eq \*(Aqsomething_else\*(Aq )
\&       {
\&          $field\->add_error("some error message" );
\&       }
\&    }
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
FormHandler Contributors \- see HTML::FormHandler
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2017 by Gerda Shank.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.