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

VERSION

10       version 2.04
11

SYNOPSIS

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

METHODS

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

SPECIAL ACTION NAMES

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

CUSTOMIZATION

254       You can set your own config settings, using either your controller
255       config or your application config.
256
257           $c->config( 'Controller::HTML::FormFu' => \%my_values );
258
259           # or
260
261           MyApp->config( 'Controller::HTML::FormFu' => \%my_values );
262
263           # or, in myapp.conf
264
265           <Controller::HTML::FormFu>
266               default_action_use_path 1
267           </Controller::HTML::FormFu>
268
269   form_method
270       Override the method-name used to create a new form object.
271
272       See "form".
273
274       Default value: "form".
275
276   form_stash
277       Sets the stash key name used to store the form object.
278
279       Default value: "form".
280
281   form_attr
282       Sets the attribute name used to load the
283       Catalyst::Controller::HTML::FormFu::Action::Form action.
284
285       Default value: "Form".
286
287   config_attr
288       Sets the attribute name used to load the
289       Catalyst::Controller::HTML::FormFu::Action::Config action.
290
291       Default value: "FormConfig".
292
293   method_attr
294       Sets the attribute name used to load the
295       Catalyst::Controller::HTML::FormFu::Action::Method action.
296
297       Default value: "FormMethod".
298
299   form_action
300       Sets which package will be used by the Form() action.
301
302       Probably only useful if you want to create a sub-class which provides
303       custom behaviour.
304
305       Default value: "Catalyst::Controller::HTML::FormFu::Action::Form".
306
307   config_action
308       Sets which package will be used by the Config() action.
309
310       Probably only useful if you want to create a sub-class which provides
311       custom behaviour.
312
313       Default value: "Catalyst::Controller::HTML::FormFu::Action::Config".
314
315   method_action
316       Sets which package will be used by the Method() action.
317
318       Probably only useful if you want to create a sub-class which provides
319       custom behaviour.
320
321       Default value: "Catalyst::Controller::HTML::FormFu::Action::Method".
322
323   constructor
324       Pass common defaults to the HTML::FormFu constructor.
325
326       These values are used by all of the action attributes, and by the
327       "$self->form" method.
328
329       Default value: "{}".
330
331   config_callback
332       Arguments: bool
333
334       If true, a coderef is passed to "$form->config_callback->{plain_value}"
335       which replaces any instance of "__uri_for(URI)__" found in form config
336       files with the result of passing the "URI" argument to "uri_for" in
337       Catalyst.
338
339       The form "__uri_for(URI, PATH, PARTS)__" is also supported, which is
340       equivalent to "$c->uri_for( 'URI', \@ARGS )". At this time, there is no
341       way to pass query values equivalent to "$c->uri_for( 'URI', \@ARGS,
342       \%QUERY_VALUES )".
343
344       The second codeword that is being replaced is "__path_to( @DIRS )__".
345       Any instance is replaced with the result of passing the "DIRS"
346       arguments to "path_to" in Catalyst. Don't use qoutationmarks as they
347       would become part of the path.
348
349       Default value: 1
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

DISCONTINUED CONFIG SETTINGS

429   config_file_ext
430       Support for this has now been removed. Config files are now searched
431       for, with any file extension supported by Config::Any.
432
433   config_file_path
434       Support for this has now been removed. Use
435       "{constructor}{config_file_path}" instead.
436

CAVEATS

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

AUTHORS

448       •   Carl Franks <cpan@fireartist.com>
449
450       •   Nigel Metheringham <nigelm@cpan.org>
451
452       •   Dean Hamstead <dean@bytefoundry.com.au>
453
455       This software is copyright (c) 2007-2018 by Carl Franks / Nigel
456       Metheringham / Dean Hamstead.
457
458       This is free software; you can redistribute it and/or modify it under
459       the same terms as the Perl 5 programming language system itself.
460

SUPPORT

462   Perldoc
463       You can find documentation for this module with the perldoc command.
464
465         perldoc Catalyst::Controller::HTML::FormFu
466
467   Websites
468       The following websites have more information about this module, and may
469       be of help to you. As always, in addition to those websites please use
470       your favorite search engine to discover more resources.
471
472       •   MetaCPAN
473
474           A modern, open-source CPAN search engine, useful to view POD in
475           HTML format.
476
477           <http://metacpan.org/release/Catalyst-Controller-HTML-FormFu>
478
479       •   Search CPAN
480
481           The default CPAN search engine, useful to view POD in HTML format.
482
483           <http://search.cpan.org/dist/Catalyst-Controller-HTML-FormFu>
484
485       •   RT: CPAN's Bug Tracker
486
487           The RT ( Request Tracker ) website is the default bug/issue
488           tracking system for CPAN.
489
490           <https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Controller-HTML-FormFu>
491
492       •   AnnoCPAN
493
494           The AnnoCPAN is a website that allows community annotations of Perl
495           module documentation.
496
497           <http://annocpan.org/dist/Catalyst-Controller-HTML-FormFu>
498
499       •   CPAN Ratings
500
501           The CPAN Ratings is a website that allows community ratings and
502           reviews of Perl modules.
503
504           <http://cpanratings.perl.org/d/Catalyst-Controller-HTML-FormFu>
505
506       •   CPAN Forum
507
508           The CPAN Forum is a web forum for discussing Perl modules.
509
510           <http://cpanforum.com/dist/Catalyst-Controller-HTML-FormFu>
511
512       •   CPANTS
513
514           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
515           of a distribution.
516
517           <http://cpants.cpanauthors.org/dist/Catalyst-Controller-HTML-FormFu>
518
519       •   CPAN Testers
520
521           The CPAN Testers is a network of smokers who run automated tests on
522           uploaded CPAN distributions.
523
524           <http://www.cpantesters.org/distro/C/Catalyst-Controller-HTML-FormFu>
525
526       •   CPAN Testers Matrix
527
528           The CPAN Testers Matrix is a website that provides a visual
529           overview of the test results for a distribution on various
530           Perls/platforms.
531
532           <http://matrix.cpantesters.org/?dist=Catalyst-Controller-HTML-FormFu>
533
534       •   CPAN Testers Dependencies
535
536           The CPAN Testers Dependencies is a website that shows a chart of
537           the test results of all dependencies for a distribution.
538
539           <http://deps.cpantesters.org/?module=Catalyst::Controller::HTML::FormFu>
540
541   Bugs / Feature Requests
542       Please report any bugs or feature requests by email to
543       "bug-catalyst-controller-html-formfu at rt.cpan.org", or through the
544       web interface at
545       <https://rt.cpan.org/Public/Bug/Report.html?Queue=Catalyst-Controller-HTML-FormFu>.
546       You will be automatically notified of any progress on the request by
547       the system.
548
549   Source Code
550       The code is open to the world, and available for you to hack on. Please
551       feel free to browse it and play with it, or whatever. If you want to
552       contribute patches, please send me a diff or prod me to pull from your
553       repository :)
554
555       <https://github.com/FormFu/Catalyst-Controller-HTML-FormFu>
556
557         git clone https://github.com/FormFu/Catalyst-Controller-HTML-FormFu.git
558

CONTRIBUTORS

560       •   Aran Deltac <aran@ziprecruiter.com>
561
562       •   bricas <brian.cassidy@gmail.com>
563
564       •   dandv <ddascalescu@gmail.com>
565
566       •   fireartist <fireartist@gmail.com>
567
568       •   lestrrat <lestrrat+github@gmail.com>
569
570       •   marcusramberg <marcus.ramberg@gmail.com>
571
572       •   mariominati <mario.minati@googlemail.com>
573
574       •   Moritz Onken <1nd@gmx.de>
575
576       •   Moritz Onken <onken@netcubed.de>
577
578       •   Nigel Metheringham <nm9762github@muesli.org.uk>
579
580       •   omega <andreas.marienborg@gmail.com>
581
582       •   Petr Písař <ppisar@redhat.com>
583
584
585
586perl v5.34.0                      2022-01-C2a0talyst::Controller::HTML::FormFu(3)
Impressum