Catalyst::Controller::HTML::FormFu(3pm)

1Catalyst::Controller::HUTsMeLr::CFoonrtmrFiub(u3t)ed PerClatDaolcyusmte:n:tCaotnitornoller::HTML::FormFu(3)
2
3
4

NAME

6       Catalyst::Controller::HTML::FormFu - Catalyst integration for
7       HTML::FormFu
8

SYNOPSIS

10           package MyApp::Controller::My::Controller;
11
12           use base 'Catalyst::Controller::HTML::FormFu';
13
14           sub index : Local {
15               my ( $self, $c ) = @_;
16
17               # doesn't use an Attribute to make a form
18               # can get an empty form from $self->form()
19
20               my $form = $self->form();
21           }
22
23           sub foo : Local : Form {
24               my ( $self, $c ) = @_;
25
26               # using the Form attribute is equivalent to:
27               #
28               # my $form = $self->form;
29               #
30               # $form->process;
31               #
32               # $c->stash->{form} = $form;
33           }
34
35           sub bar : Local : FormConfig {
36               my ( $self, $c ) = @_;
37
38               # using the FormConfig attribute is equivalent to:
39               #
40               # my $form = $self->form;
41               #
42               # $form->load_config_filestem('root/forms/my/controller/bar');
43               #
44               # $form->process;
45               #
46               # $c->stash->{form} = $form;
47               #
48               # so you only need to do the following...
49
50               my $form = $c->stash->{form};
51
52               if ( $form->submitted_and_valid ) {
53                   do_something();
54               }
55           }
56
57           sub baz : Local : FormConfig('my_config') {
58               my ( $self, $c ) = @_;
59
60               # using the FormConfig attribute with an argument is equivalent to:
61               #
62               # my $form = $self->form;
63               #
64               # $form->load_config_filestem('root/forms/my_config');
65               #
66               # $form->process;
67               #
68               # $c->stash->{form} = $form;
69               #
70               # so you only need to do the following...
71
72               my $form = $c->stash->{form};
73
74               if ( $form->submitted_and_valid ) {
75                   do_something();
76               }
77           }
78
79           sub quux : Local : FormMethod('load_form') {
80               my ( $self, $c ) = @_;
81
82               # using the FormMethod attribute with an argument is equivalent to:
83               #
84               # my $form = $self->form;
85               #
86               # $form->populate( $c->load_form );
87               #
88               # $form->process;
89               #
90               # $c->stash->{form} = $form;
91               #
92               # so you only need to do the following...
93
94               my $form = $c->stash->{form};
95
96               if ( $form->submitted_and_valid ) {
97                   do_something();
98               }
99           }
100
101           sub load_form {
102               my ( $self, $c ) = @_;
103
104               # Automatically called by the above FormMethod('load_form') action.
105               # Called as a method on the controller object, with the context
106               # object as an argument.
107
108               # Must return a hash-ref suitable to be fed to $form->populate()
109           }
110
111       You can also use specially-named actions that will only be called under
112       certain circumstances.
113
114           sub edit : Chained('group') : PathPart : Args(0) : FormConfig { }
115
116           sub edit_FORM_VALID {
117               my ( $self, $c ) = @_;
118
119               my $form  = $c->stash->{form};
120               my $group = $c->stash->{group};
121
122               $form->model->update( $group );
123
124               $c->response->redirect( $c->uri_for( '/group', $group->id ) );
125           }
126
127           sub edit_FORM_NOT_SUBMITTED {
128               my ( $self, $c ) = @_;
129
130               my $form  = $c->stash->{form};
131               my $group = $c->stash->{group};
132
133               $form->model->default_values( $group );
134           }
135

METHODS

137   form
138       This creates a new HTML::FormFu object, passing as it's argument the
139       contents of the "constructor" config value.
140
141       This is useful when using the ConfigForm() or MethodForm() action
142       attributes, to create a 2nd form which isn't populated using a config-
143       file or method return value.
144
145           sub foo : Local {
146               my ( $self, $c ) = @_;
147
148               my $form = $self->form;
149           }
150
151       Note that when using this method, the form's query method is not
152       populated with the Catalyst request object.
153

SPECIAL ACTION NAMES

155       An example showing how a complicated action method can be broken down
156       into smaller sections, making it clearer which code will be run, and
157       when.
158
159           sub edit : Local : FormConfig {
160               my ( $self, $c ) = @_;
161
162               my $form  = $c->stash->{form};
163               my $group = $c->stash->{group};
164
165               $c->detach('/unauthorised') unless $c->user->can_edit( $group );
166
167               if ( $form->submitted_and_valid ) {
168                   $form->model->update( $group );
169
170                   $c->response->redirect( $c->uri_for('/group', $group->id ) );
171                   return;
172               }
173               elsif ( !$form->submitted ) {
174                   $form->model->default_values( $group );
175               }
176
177               $self->_add_breadcrumbs_nav( $c, $group );
178           }
179
180       Instead becomes...
181
182           sub edit : Local : FormConfig {
183               my ( $self, $c ) = @_;
184
185               $c->detach('/unauthorised') unless $c->user->can_edit(
186                   $c->stash->{group}
187               );
188           }
189
190           sub edit_FORM_VALID {
191               my ( $self, $c ) = @_;
192
193               my $group = $c->stash->{group};
194
195               $c->stash->{form}->model->update( $group );
196
197               $c->response->redirect( $c->uri_for('/group', $group->id ) );
198           }
199
200           sub edit_FORM_NOT_SUBMITTED {
201               my ( $self, $c ) = @_;
202
203               $c->stash->{form}->model->default_values(
204                   $c->stash->{group}
205               );
206           }
207
208           sub edit_FORM_RENDER {
209               my ( $self, $c ) = @_;
210
211               $self->_add_breadcrumbs_nav( $c, $c->stash->{group} );
212           }
213
214       For any action method that uses a "Form", "FormConfig" or "FormMethod"
215       attribute, you can add extra methods that use the naming conventions
216       below.
217
218       These methods will be called after the original, plainly named action
219       method.
220
221   _FORM_VALID
222       Run when the form has been submitted and has no errors.
223
224   _FORM_SUBMITTED
225       Run when the form has been submitted, regardless of whether or not
226       there was errors.
227
228   _FORM_COMPLETE
229       For MultiForms, is run if the MultiForm is completed.
230
231   _FORM_NOT_VALID
232       Run when the form has been submitted and there were errors.
233
234   _FORM_NOT_SUBMITTED
235       Run when the form has not been submitted.
236
237   _FORM_NOT_COMPLETE
238       For MultiForms, is run if the MultiForm is not completed.
239
240   _FORM_RENDER
241       For normal "Form" base classes, this subroutine is run after any of the
242       other special methods, unless "$form->submitted_and_valid" is true.
243
244       For "MultiForm" base classes, this subroutine is run after any of the
245       other special methods, unless "$multi->complete" is true.
246

CUSTOMIZATION

248       You can set your own config settings, using either your controller
249       config or your application config.
250
251           $c->config( 'Controller::HTML::FormFu' => \%my_values );
252
253           # or
254
255           MyApp->config( 'Controller::HTML::FormFu' => \%my_values );
256
257           # or, in myapp.conf
258
259           <Controller::HTML::FormFu>
260               default_action_use_path 1
261           </Controller::HTML::FormFu>
262
263   form_method
264       Override the method-name used to create a new form object.
265
266       See "form".
267
268       Default value: "form".
269
270   form_stash
271       Sets the stash key name used to store the form object.
272
273       Default value: "form".
274
275   form_attr
276       Sets the attribute name used to load the
277       Catalyst::Controller::HTML::FormFu::Action::Form action.
278
279       Default value: "Form".
280
281   config_attr
282       Sets the attribute name used to load the
283       Catalyst::Controller::HTML::FormFu::Action::Config action.
284
285       Default value: "FormConfig".
286
287   method_attr
288       Sets the attribute name used to load the
289       Catalyst::Controller::HTML::FormFu::Action::Method action.
290
291       Default value: "FormMethod".
292
293   form_action
294       Sets which package will be used by the Form() action.
295
296       Probably only useful if you want to create a sub-class which provides
297       custom behaviour.
298
299       Default value: "Catalyst::Controller::HTML::FormFu::Action::Form".
300
301   config_action
302       Sets which package will be used by the Config() action.
303
304       Probably only useful if you want to create a sub-class which provides
305       custom behaviour.
306
307       Default value: "Catalyst::Controller::HTML::FormFu::Action::Config".
308
309   method_action
310       Sets which package will be used by the Method() action.
311
312       Probably only useful if you want to create a sub-class which provides
313       custom behaviour.
314
315       Default value: "Catalyst::Controller::HTML::FormFu::Action::Method".
316
317   constructor
318       Pass common defaults to the HTML::FormFu constructor.
319
320       These values are used by all of the action attributes, and by the
321       "$self->form" method.
322
323       Default value: "{}".
324
325   config_callback
326       Arguments: bool
327
328       If true, a coderef is passed to "$form->config_callback->{plain_value}"
329       which replaces any instance of "__uri_for(URI)__" found in form config
330       files with the result of passing the "URI" argument to "uri_for" in
331       Catalyst.
332
333       The form "__uri_for(URI, PATH, PARTS)__" is also supported, which is
334       equivalent to "$c->uri_for( 'URI', \@ARGS )". At this time, there is no
335       way to pass query values equivalent to "$c->uri_for( 'URI', \@ARGS,
336       \%QUERY_VALUES )".
337
338       The second codeword that is being replaced is "__path_to( @DIRS )__".
339       Any instance is replaced with the result of passing the "DIRS"
340       arguments to "path_to" in Catalyst.  Don't use qoutationmarks as they
341       would become part of the path.
342
343       Default value: 1
344
345   config_file_path
346       Location of the form config files, used when creating a form with the
347       "FormConfig" action controller.
348
349       Default Value: "$c->path_to( 'root', 'forms' )"
350
351   default_action_use_name
352       If set to a true value the action for the form will be set to the
353       currently called action name.
354
355       Default value: "false".
356
357   default_action_use_path
358       If set to a true value the action for the form will be set to the
359       currently called action path.  The action path includes concurrent to
360       action name additioal parameters which were code inside the path.
361
362       Default value: "false".
363
364       Example:
365
366           action: /foo/bar
367           called uri contains: /foo/bar/1
368
369           # default_action_use_name => 1 leads to:
370           $form->action = /foo/bar
371
372           # default_action_use_path => 1 leads to:
373           $form->action = /foo/bar/1
374
375   model_stash
376       Arguments: \%stash_keys_to_model_names
377
378       Used to place Catalyst models on the form stash.
379
380       If it's being used to make a DBIx::Class schema available for
381       "options_from_model" in HTML::FormFu::Model::DBIC, for "Select" and
382       other Group-type elements - then the hash-key must be "schema". For
383       example, if your schema model class is "MyApp::Model::MySchema", you
384       would set "model_stash" like so:
385
386           <Controller::HTML::FormFu>
387               <model_stash>
388                   schema MySchema
389               </model_stash>
390           </Controller::HTML::FormFu>
391
392   context_stash
393       To allow your form validation packages, etc, access to the catalyst
394       context, a weakened reference of the context is copied into the form's
395       stash.
396
397           $form->stash->{context};
398
399       This setting allows you to change the key name used in the form stash.
400
401       Default value: "context"
402
403   languages_from_context
404       If you're using a L10N / I18N plugin such as Catalyst::Plugin::I18N
405       which provides a "languages" method that returns a list of valid
406       languages to use for the currect request - and you want to use formfu's
407       built-in I18N packages, then setting "languages_from_context"
408
409   localize_from_context
410       If you're using a L10N / I18N plugin such as Catalyst::Plugin::I18N
411       which provides it's own "localize" method, you can set
412       localize_from_context to use that method for formfu's localization.
413
414   request_token_enable
415       If true, adds an instance of HTML::FormFu::Plugin::RequestToken to
416       every form, to stop accidental double-submissions of data and to
417       prevent CSRF attacks.
418
419   request_token_field_name
420       Defaults to "_token".
421
422   request_token_session_key
423       Defaults to "__token".
424
425   request_token_expiration_time
426       Defaults to 3600.
427

DEPRECATED CONFIG SETTINGS

429   config_file_ext
430       This is now unnecessary, and has been removed. Config files are now
431       searched for, with any file extension supported by Config::Any.
432

CAVEATS

434       When using the "Form" action attribute to create an empty form, you
435       must call $form->process after populating the form.  However, you don't
436       need to pass any arguments to "process", as the Catalyst request object
437       will have automatically been set in $form->query.
438
439       When using the "FormConfig" and "FormMethod" action attributes, if you
440       make any modifications to the form, such as adding or changing it's
441       elements, you must call $form->process before rendering the form.
442

AUTHOR

447       Carl Franks, "cfranks@cpan.org"
448

COPYRIGHT AND LICENSE

450       Copyright (C) 2007 by Carl Franks
451
452       This library is free software; you can redistribute it and/or modify it
453       under the same terms as Perl itself, either Perl version 5.8.8 or, at
454       your option, any later version of Perl 5 you may have available.
455
456
457
458perl v5.12.0                      2009-12-C1a0talyst::Controller::HTML::FormFu(3)