1Catalyst::Controller::HUTsMeLr::CFoonrtmrFiub(u3t)ed PerClatDaolcyusmte:n:tCaotnitornoller::HTML::FormFu(3)
2
6 Catalyst::Controller::HTML::FormFu - Catalyst integration for
7 HTML::FormFu
8
10 version 2.04
11
13 package MyApp::Controller::My::Controller;
14 use Moose;
16 use namespace::autoclean;
17 BEGIN { extends 'Catalyst::Controller::HTML::FormFu'; }
19 sub index : Local {
21 my ( $self, $c ) = @_;
22 # doesn't use an Attribute to make a form
24 # can get an empty form from $self->form()
25 my $form = $self->form();
27 }
28 sub foo : Local : Form {
30 my ( $self, $c ) = @_;
31 # 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 sub bar : Local : FormConfig {
42 my ( $self, $c ) = @_;
43 # 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 my $form = $c->stash->{form};
57 if ( $form->submitted_and_valid ) {
59 do_something();
60 }
61 }
62 sub baz : Local : FormConfig('my_config') {
64 my ( $self, $c ) = @_;
65 # 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 my $form = $c->stash->{form};
79 if ( $form->submitted_and_valid ) {
81 do_something();
82 }
83 }
84 sub quux : Local : FormMethod('load_form') {
86 my ( $self, $c ) = @_;
87 # 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 my $form = $c->stash->{form};
101 if ( $form->submitted_and_valid ) {
103 do_something();
104 }
105 }
106 sub load_form {
108 my ( $self, $c ) = @_;
109 # 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 # Must return a hash-ref suitable to be fed to $form->populate()
115 }
116 You can also use specially-named actions that will only be called under
118 certain circumstances.
119 sub edit : Chained('group') : PathPart : Args(0) : FormConfig { }
121 sub edit_FORM_VALID {
123 my ( $self, $c ) = @_;
124 my $form = $c->stash->{form};
126 my $group = $c->stash->{group};
127 $form->model->update( $group );
129 $c->response->redirect( $c->uri_for( '/group', $group->id ) );
131 }
132 sub edit_FORM_NOT_SUBMITTED {
134 my ( $self, $c ) = @_;
135 my $form = $c->stash->{form};
137 my $group = $c->stash->{group};
138 $form->model->default_values( $group );
140 }
141
143 form
144 This creates a new HTML::FormFu object, passing as it's argument the
145 contents of the "constructor" config value.
146 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 sub foo : Local {
152 my ( $self, $c ) = @_;
153 my $form = $self->form;
155 }
156 Note that when using this method, the form's query method is not
158 populated with the Catalyst request object.
159
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 sub edit : Local : FormConfig {
166 my ( $self, $c ) = @_;
167 my $form = $c->stash->{form};
169 my $group = $c->stash->{group};
170 $c->detach('/unauthorised') unless $c->user->can_edit( $group );
172 if ( $form->submitted_and_valid ) {
174 $form->model->update( $group );
175 $c->response->redirect( $c->uri_for('/group', $group->id ) );
177 return;
178 }
179 elsif ( !$form->submitted ) {
180 $form->model->default_values( $group );
181 }
182 $self->_add_breadcrumbs_nav( $c, $group );
184 }
185 Instead becomes...
187 sub edit : Local : FormConfig {
189 my ( $self, $c ) = @_;
190 $c->detach('/unauthorised') unless $c->user->can_edit(
192 $c->stash->{group}
193 );
194 }
195 sub edit_FORM_VALID {
197 my ( $self, $c ) = @_;
198 my $group = $c->stash->{group};
200 $c->stash->{form}->model->update( $group );
202 $c->response->redirect( $c->uri_for('/group', $group->id ) );
204 }
205 sub edit_FORM_NOT_SUBMITTED {
207 my ( $self, $c ) = @_;
208 $c->stash->{form}->model->default_values(
210 $c->stash->{group}
211 );
212 }
213 sub edit_FORM_RENDER {
215 my ( $self, $c ) = @_;
216 $self->_add_breadcrumbs_nav( $c, $c->stash->{group} );
218 }
219 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 These methods will be called after the original, plainly named action
225 method.
226 _FORM_VALID
228 Run when the form has been submitted and has no errors.
229 _FORM_SUBMITTED
231 Run when the form has been submitted, regardless of whether or not
232 there was errors.
233 _FORM_COMPLETE
235 For MultiForms, is run if the MultiForm is completed.
236 _FORM_NOT_VALID
238 Run when the form has been submitted and there were errors.
239 _FORM_NOT_SUBMITTED
241 Run when the form has not been submitted.
242 _FORM_NOT_COMPLETE
244 For MultiForms, is run if the MultiForm is not completed.
245 _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 For "MultiForm" base classes, this subroutine is run after any of the
251 other special methods, unless "$multi->complete" is true.
252
254 You can set your own config settings, using either your controller
255 config or your application config.
256 $c->config( 'Controller::HTML::FormFu' => \%my_values );
258 # or
260 MyApp->config( 'Controller::HTML::FormFu' => \%my_values );
262 # or, in myapp.conf
264 <Controller::HTML::FormFu>
266 default_action_use_path 1
267 </Controller::HTML::FormFu>
268 form_method
270 Override the method-name used to create a new form object.
271 See "form".
273 Default value: "form".
275 form_stash
277 Sets the stash key name used to store the form object.
278 Default value: "form".
280 form_attr
282 Sets the attribute name used to load the
283 Catalyst::Controller::HTML::FormFu::Action::Form action.
284 Default value: "Form".
286 config_attr
288 Sets the attribute name used to load the
289 Catalyst::Controller::HTML::FormFu::Action::Config action.
290 Default value: "FormConfig".
292 method_attr
294 Sets the attribute name used to load the
295 Catalyst::Controller::HTML::FormFu::Action::Method action.
296 Default value: "FormMethod".
298 form_action
300 Sets which package will be used by the Form() action.
301 Probably only useful if you want to create a sub-class which provides
303 custom behaviour.
304 Default value: "Catalyst::Controller::HTML::FormFu::Action::Form".
306 config_action
308 Sets which package will be used by the Config() action.
309 Probably only useful if you want to create a sub-class which provides
311 custom behaviour.
312 Default value: "Catalyst::Controller::HTML::FormFu::Action::Config".
314 method_action
316 Sets which package will be used by the Method() action.
317 Probably only useful if you want to create a sub-class which provides
319 custom behaviour.
320 Default value: "Catalyst::Controller::HTML::FormFu::Action::Method".
322 constructor
324 Pass common defaults to the HTML::FormFu constructor.
325 These values are used by all of the action attributes, and by the
327 "$self->form" method.
328 Default value: "{}".
330 config_callback
332 Arguments: bool
333 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 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 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 Default value: 1
350 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 Default value: "false".
356 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 Default value: "false".
363 Example:
365 action: /foo/bar
367 called uri contains: /foo/bar/1
368 # default_action_use_name => 1 leads to:
370 $form->action = /foo/bar
371 # default_action_use_path => 1 leads to:
373 $form->action = /foo/bar/1
374 model_stash
376 Arguments: \%stash_keys_to_model_names
377 Used to place Catalyst models on the form stash.
379 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 <Controller::HTML::FormFu>
387 <model_stash>
388 schema MySchema
389 </model_stash>
390 </Controller::HTML::FormFu>
391 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 $form->stash->{context};
398 This setting allows you to change the key name used in the form stash.
400 Default value: "context"
402 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 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 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 request_token_field_name
420 Defaults to "_token".
421 request_token_session_key
423 Defaults to "__token".
424 request_token_expiration_time
426 Defaults to 3600.
427
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 config_file_path
434 Support for this has now been removed. Use
435 "{constructor}{config_file_path}" instead.
436
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 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
448 • Carl Franks <cpan@fireartist.com>
449 • Nigel Metheringham <nigelm@cpan.org>
451 • Dean Hamstead <dean@bytefoundry.com.au>
453
455 This software is copyright (c) 2007-2018 by Carl Franks / Nigel
456 Metheringham / Dean Hamstead.
457 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
462 Perldoc
463 You can find documentation for this module with the perldoc command.
464 perldoc Catalyst::Controller::HTML::FormFu
466 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 • MetaCPAN
473 A modern, open-source CPAN search engine, useful to view POD in
475 HTML format.
476 <http://metacpan.org/release/Catalyst-Controller-HTML-FormFu>
478 • Search CPAN
480 The default CPAN search engine, useful to view POD in HTML format.
482 <http://search.cpan.org/dist/Catalyst-Controller-HTML-FormFu>
484 • RT: CPAN's Bug Tracker
486 The RT ( Request Tracker ) website is the default bug/issue
488 tracking system for CPAN.
489 <https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Controller-HTML-FormFu>
491 • AnnoCPAN
493 The AnnoCPAN is a website that allows community annotations of Perl
495 module documentation.
496 <http://annocpan.org/dist/Catalyst-Controller-HTML-FormFu>
498 • CPAN Ratings
500 The CPAN Ratings is a website that allows community ratings and
502 reviews of Perl modules.
503 <http://cpanratings.perl.org/d/Catalyst-Controller-HTML-FormFu>
505 • CPAN Forum
507 The CPAN Forum is a web forum for discussing Perl modules.
509 <http://cpanforum.com/dist/Catalyst-Controller-HTML-FormFu>
511 • CPANTS
513 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
515 of a distribution.
516 <http://cpants.cpanauthors.org/dist/Catalyst-Controller-HTML-FormFu>
518 • CPAN Testers
520 The CPAN Testers is a network of smokers who run automated tests on
522 uploaded CPAN distributions.
523 <http://www.cpantesters.org/distro/C/Catalyst-Controller-HTML-FormFu>
525 • CPAN Testers Matrix
527 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 <http://matrix.cpantesters.org/?dist=Catalyst-Controller-HTML-FormFu>
533 • CPAN Testers Dependencies
535 The CPAN Testers Dependencies is a website that shows a chart of
537 the test results of all dependencies for a distribution.
538 <http://deps.cpantesters.org/?module=Catalyst::Controller::HTML::FormFu>
540 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 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 <https://github.com/FormFu/Catalyst-Controller-HTML-FormFu>
556 git clone https://github.com/FormFu/Catalyst-Controller-HTML-FormFu.git
558
560 • Aran Deltac <aran@ziprecruiter.com>
561 • bricas <brian.cassidy@gmail.com>
563 • dandv <ddascalescu@gmail.com>
565 • fireartist <fireartist@gmail.com>
567 • lestrrat <lestrrat+github@gmail.com>
569 • marcusramberg <marcus.ramberg@gmail.com>
571 • mariominati <mario.minati@googlemail.com>
573 • Moritz Onken <1nd@gmx.de>
575 • Moritz Onken <onken@netcubed.de>
577 • Nigel Metheringham <nm9762github@muesli.org.uk>
579 • omega <andreas.marienborg@gmail.com>
581 • Petr Písař <ppisar@redhat.com>
583perl v5.34.0 2022-01-C2a0talyst::Controller::HTML::FormFu(3)