1HTML::FormHandler::ManuUasle:r:CCaotnatlryisbtu(t3e)d PeHrTlMLD:o:cFuomremnHtaantdiloenr::Manual::Catalyst(3)
2
3
4

NAME

6       HTML::FormHandler::Manual::Catalyst - using HFH forms in Catalyst
7

VERSION

9       version 0.40068
10

SYNOPSIS

12       Manual Index
13
14       This part of the FormHandler Manual describes the use of the
15       HTML::FormHandler package in Catalyst controllers.
16
17       See the other FormHandler documentation at HTML::FormHandler::Manual,
18       or the base class at HTML::FormHandler.
19

DESCRIPTION

21       Although HTML::FormHandler can be used in any Perl web application,
22       module, or script, one of its most common uses is in Catalyst
23       applications.
24
25       Using a form takes only a few lines of code, so it's not necessary to
26       have a Catalyst base controller, although you could make a base
27       controller for FormHandler if you're doing more than the basics.
28
29   A Controller Example
30       The following example uses chained dispatching. The 'form' method is
31       called by both the create and edit actions.
32
33          package BookDB::Controller::Borrower;
34
35          use Moose;
36          BEGIN { extends 'Catalyst::Controller' }
37
38          use BookDB::Form::Borrower;
39
40          sub borrower_base : Chained PathPart('borrower') CaptureArgs(0) { }
41
42          sub list : Chained('borrower_base') PathPart('list') Args(0) {
43             my ( $self, $c ) = @_;
44             my $borrowers = [ $c->model('DB::Borrower')->all ];
45             my @columns = ( 'name', 'email' );
46             $c->stash( borrowers => $borrowers, columns => \@columns,
47                        template => 'borrower/list.tt' );
48          }
49
50          sub add : Chained('borrower_base') PathPart('add') Args(0) {
51             my ( $self, $c ) = @_;
52             # Create the empty borrower row for the form
53             $c->stash( borrower => $c->model('DB::Borrower')->new_result({}) );
54             return $self->form($c);
55          }
56
57          sub item : Chained('borrower_base') PathPart('') CaptureArgs(1) {
58             my ( $self, $c, $borrower_id ) = @_;
59             $c->stash( borrower => $c->model('DB::Borrower')->find($borrower_id) );
60          }
61
62          sub edit : Chained('item') PathPart('edit') Args(0) {
63             my ( $self, $c ) = @_;
64             return $self->form($c);
65          }
66
67          sub form {
68             my ( $self, $c ) = @_;
69
70             my $form = BookDB::Form::Borrower->new;
71             $c->stash( form => $form, template => 'borrower/form.tt' );
72             return unless $form->process( item => $c->stash->{borrower},
73                params => $c->req->parameters );
74             $c->res->redirect( $c->uri_for($self->action_for('list')) );
75          }
76
77          sub delete : Chained('item') PathPart('delete') Args(0) {
78             my ( $self, $c ) = @_;
79
80             $c->stash->{borrower}->delete;
81             $c->res->redirect( $c->uri_for($c->action_for('list')) );
82          }
83
84          1;
85
86   Another way to set up your form
87       If you are setting the schema or other form attributes (such as the
88       user_id, or other attributes) on your form you could create a base
89       controller that would set these in the form on each call using
90       Catalyst::Component::InstancePerContext, or set them in a base Chained
91       method.
92
93          sub book_base : Chained PathPart('book') CaptureArgs(0) {
94             my ( $self, $c ) = @_;
95             my $form = MyApp::Form->new;
96             $form->schema( $c->model('DB')->schema );
97             $form->params( $c->req->parameters );
98             $form->user_id( $c->user->id );
99             $c->stash( form => $form );
100          }
101
102       Then you could just pass in the item_id when the form is processed.
103
104          return unless $c->stash->{form}->process( item_id => $id );
105
106   Putting a form in a Moose attribute
107       You can also put your form in a Moose attribute in the controller.
108
109           package MyApp::Controller::Book;
110           use Moose;
111           BEGIN { extends 'Catalyst::Controller'; }
112           use MyApp::Form::Book;
113           has 'edit_form' => ( isa => 'MyApp::Form::Book', is => 'rw',
114              lazy => 1, default => sub { MyApp::Form::Book->new } );
115
116       Then you can process the form in your actions with
117       "$self->edit_form->process( params => $c->req->body_parameters );" or
118       "my $result = $self->edit_form->run( params => $c->req->body_parameters
119       );".
120
121   Using  HTML::FillInForm
122       If you want to use HTML::FillInForm to fill in values instead of doing
123       it in directly in a template using either the field or the form 'fif'
124       methods, you can use Catalyst::View::FillInForm on your view class:
125
126           package MyApp::View::TT;
127           use Moose;
128           with 'Catalyst::View::FillInForm';
129           ....
130           1;
131
132       and set the 'fif' hash in the 'fillinform' stash variable:
133
134           $self->form->process( ... );
135           $c->stash( fillinform => $self->form->fif );
136           return unless $form->validated;
137
138       When the 'fillinform' stash variable is set, HTML::FillInForm will
139       automatically be used by your view to fill in the form values. This can
140       be very helpful when you want to build your forms by hand, or when you
141       have legacy forms that you're just trying to hook up to FormHandler.
142
143   The Catalyst context
144       FormHandler has a 'ctx' attribute that can be used to set the Catalyst
145       context (or anything you want, really). But if you can avoid passing in
146       the context, you should do so, because you're mixing up your MVC and it
147       makes it much more difficult to test your forms. But if you need to do
148       it, you can:
149
150           my $form = MyApp::Form->new( ctx => $c );
151
152       Usually you should prefer to add new attributes to your form:
153
154           package MyApp::Form;
155           use HTML::FormHandler::Moose;
156           extends 'HTML::FormHandler';
157
158           has 'user_id' => ( is => 'rw' );
159           has 'hostname' => ( is => 'rw' );
160           has 'captcha_store' => ( is => 'rw' );
161           ....
162           1;
163
164       Then just pass the attributes in on new:
165
166           my $form => MyApp::Form->new( user_id => $c->user->id, hostname => $c->req->host,
167               captcha_store => $c->{session}->{captcha} );
168
169       Or set them using accessors:
170
171           $form->user_id( $c->user->id );
172           $form->hostname( $c->req->host );
173           $form->captcha_store( $c->{session}->{captcha} );
174
175       Then you can access these attributes in your form validation methods:
176
177           sub validate_selection {
178              my ( $self, $field ) = @_;
179              if( $field->value eq 'something' && $self->hostname eq 'something_else' )
180              {
181                 $field->add_error("some error message" );
182              }
183           }
184

AUTHOR

186       FormHandler Contributors - see HTML::FormHandler
187

189       This software is copyright (c) 2017 by Gerda Shank.
190
191       This is free software; you can redistribute it and/or modify it under
192       the same terms as the Perl 5 programming language system itself.
193
194
195
196perl v5.36.0                      2023-01H-T2M0L::FormHandler::Manual::Catalyst(3)
Impressum