Debian Codegraph @

README

raw
1 NAME
2
3 Catalyst::Controller::HTML::FormFu - Catalyst integration for
4 HTML::FormFu
5
6 VERSION
7
8 version 2.04
9
10 SYNOPSIS
11
12 package MyApp::Controller::My::Controller;
13
14 use Moose;
15 use namespace::autoclean;
16
17 BEGIN { extends 'Catalyst::Controller::HTML::FormFu'; }
18
19 sub index : Local {
20 my ( $self, $c ) = @_;
21
22 # doesn't use an Attribute to make a form
23 # can get an empty form from $self->form()
24
25 my $form = $self->form();
26 }
27
28 sub foo : Local : Form {
29 my ( $self, $c ) = @_;
30
31 # using the Form attribute is equivalent to:
32 #
33 # my $form = $self->form;
34 #
35 # $form->process;
36 #
37 # $c->stash->{form} = $form;
38 }
39
40 sub bar : Local : FormConfig {
41 my ( $self, $c ) = @_;
42
43 # using the FormConfig attribute is equivalent to:
44 #
45 # my $form = $self->form;
46 #
47 # $form->load_config_filestem('root/forms/my/controller/bar');
48 #
49 # $form->process;
50 #
51 # $c->stash->{form} = $form;
52 #
53 # so you only need to do the following...
54
55 my $form = $c->stash->{form};
56
57 if ( $form->submitted_and_valid ) {
58 do_something();
59 }
60 }
61
62 sub baz : Local : FormConfig('my_config') {
63 my ( $self, $c ) = @_;
64
65 # using the FormConfig attribute with an argument is equivalent to:
66 #
67 # my $form = $self->form;
68 #
69 # $form->load_config_filestem('root/forms/my_config');
70 #
71 # $form->process;
72 #
73 # $c->stash->{form} = $form;
74 #
75 # so you only need to do the following...
76
77 my $form = $c->stash->{form};
78
79 if ( $form->submitted_and_valid ) {
80 do_something();
81 }
82 }
83
84 sub quux : Local : FormMethod('load_form') {
85 my ( $self, $c ) = @_;
86
87 # using the FormMethod attribute with an argument is equivalent to:
88 #
89 # my $form = $self->form;
90 #
91 # $form->populate( $c->load_form );
92 #
93 # $form->process;
94 #
95 # $c->stash->{form} = $form;
96 #
97 # so you only need to do the following...
98
99 my $form = $c->stash->{form};
100
101 if ( $form->submitted_and_valid ) {
102 do_something();
103 }
104 }
105
106 sub load_form {
107 my ( $self, $c ) = @_;
108
109 # Automatically called by the above FormMethod('load_form') action.
110 # Called as a method on the controller object, with the context
111 # object as an argument.
112
113 # Must return a hash-ref suitable to be fed to $form->populate()
114 }
115
116 You can also use specially-named actions that will only be called under
117 certain circumstances.
118
119 sub edit : Chained('group') : PathPart : Args(0) : FormConfig { }
120
121 sub edit_FORM_VALID {
122 my ( $self, $c ) = @_;
123
124 my $form = $c->stash->{form};
125 my $group = $c->stash->{group};
126
127 $form->model->update( $group );
128
129 $c->response->redirect( $c->uri_for( '/group', $group->id ) );
130 }
131
132 sub edit_FORM_NOT_SUBMITTED {
133 my ( $self, $c ) = @_;
134
135 my $form = $c->stash->{form};
136 my $group = $c->stash->{group};
137
138 $form->model->default_values( $group );
139 }
140
141 METHODS
142
143 form
144
145 This creates a new HTML::FormFu object, passing as it's argument the
146 contents of the "constructor" config value.
147
148 This is useful when using the ConfigForm() or MethodForm() action
149 attributes, to create a 2nd form which isn't populated using a
150 config-file or method return value.
151
152 sub foo : Local {
153 my ( $self, $c ) = @_;
154
155 my $form = $self->form;
156 }
157
158 Note that when using this method, the form's query method is not
159 populated with the Catalyst request object.
160
161 SPECIAL ACTION NAMES
162
163 An example showing how a complicated action method can be broken down
164 into smaller sections, making it clearer which code will be run, and
165 when.
166
167 sub edit : Local : FormConfig {
168 my ( $self, $c ) = @_;
169
170 my $form = $c->stash->{form};
171 my $group = $c->stash->{group};
172
173 $c->detach('/unauthorised') unless $c->user->can_edit( $group );
174
175 if ( $form->submitted_and_valid ) {
176 $form->model->update( $group );
177
178 $c->response->redirect( $c->uri_for('/group', $group->id ) );
179 return;
180 }
181 elsif ( !$form->submitted ) {
182 $form->model->default_values( $group );
183 }
184
185 $self->_add_breadcrumbs_nav( $c, $group );
186 }
187
188 Instead becomes...
189
190 sub edit : Local : FormConfig {
191 my ( $self, $c ) = @_;
192
193 $c->detach('/unauthorised') unless $c->user->can_edit(
194 $c->stash->{group}
195 );
196 }
197
198 sub edit_FORM_VALID {
199 my ( $self, $c ) = @_;
200
201 my $group = $c->stash->{group};
202
203 $c->stash->{form}->model->update( $group );
204
205 $c->response->redirect( $c->uri_for('/group', $group->id ) );
206 }
207
208 sub edit_FORM_NOT_SUBMITTED {
209 my ( $self, $c ) = @_;
210
211 $c->stash->{form}->model->default_values(
212 $c->stash->{group}
213 );
214 }
215
216 sub edit_FORM_RENDER {
217 my ( $self, $c ) = @_;
218
219 $self->_add_breadcrumbs_nav( $c, $c->stash->{group} );
220 }
221
222 For any action method that uses a Form, FormConfig or FormMethod
223 attribute, you can add extra methods that use the naming conventions
224 below.
225
226 These methods will be called after the original, plainly named action
227 method.
228
229 _FORM_VALID
230
231 Run when the form has been submitted and has no errors.
232
233 _FORM_SUBMITTED
234
235 Run when the form has been submitted, regardless of whether or not
236 there was errors.
237
238 _FORM_COMPLETE
239
240 For MultiForms, is run if the MultiForm is completed.
241
242 _FORM_NOT_VALID
243
244 Run when the form has been submitted and there were errors.
245
246 _FORM_NOT_SUBMITTED
247
248 Run when the form has not been submitted.
249
250 _FORM_NOT_COMPLETE
251
252 For MultiForms, is run if the MultiForm is not completed.
253
254 _FORM_RENDER
255
256 For normal Form base classes, this subroutine is run after any of the
257 other special methods, unless $form->submitted_and_valid is true.
258
259 For MultiForm base classes, this subroutine is run after any of the
260 other special methods, unless $multi->complete is true.
261
262 CUSTOMIZATION
263
264 You can set your own config settings, using either your controller
265 config or your application config.
266
267 $c->config( 'Controller::HTML::FormFu' => \%my_values );
268
269 # or
270
271 MyApp->config( 'Controller::HTML::FormFu' => \%my_values );
272
273 # or, in myapp.conf
274
275 <Controller::HTML::FormFu>
276 default_action_use_path 1
277 </Controller::HTML::FormFu>
278
279 form_method
280
281 Override the method-name used to create a new form object.
282
283 See "form".
284
285 Default value: form.
286
287 form_stash
288
289 Sets the stash key name used to store the form object.
290
291 Default value: form.
292
293 form_attr
294
295 Sets the attribute name used to load the
296 Catalyst::Controller::HTML::FormFu::Action::Form action.
297
298 Default value: Form.
299
300 config_attr
301
302 Sets the attribute name used to load the
303 Catalyst::Controller::HTML::FormFu::Action::Config action.
304
305 Default value: FormConfig.
306
307 method_attr
308
309 Sets the attribute name used to load the
310 Catalyst::Controller::HTML::FormFu::Action::Method action.
311
312 Default value: FormMethod.
313
314 form_action
315
316 Sets which package will be used by the Form() 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::Form.
322
323 config_action
324
325 Sets which package will be used by the Config() action.
326
327 Probably only useful if you want to create a sub-class which provides
328 custom behaviour.
329
330 Default value: Catalyst::Controller::HTML::FormFu::Action::Config.
331
332 method_action
333
334 Sets which package will be used by the Method() action.
335
336 Probably only useful if you want to create a sub-class which provides
337 custom behaviour.
338
339 Default value: Catalyst::Controller::HTML::FormFu::Action::Method.
340
341 constructor
342
343 Pass common defaults to the HTML::FormFu constructor.
344
345 These values are used by all of the action attributes, and by the
346 $self->form method.
347
348 Default value: {}.
349
350 config_callback
351
352 Arguments: bool
353
354 If true, a coderef is passed to $form->config_callback->{plain_value}
355 which replaces any instance of __uri_for(URI)__ found in form config
356 files with the result of passing the URI argument to "uri_for" in
357 Catalyst.
358
359 The form __uri_for(URI, PATH, PARTS)__ is also supported, which is
360 equivalent to $c->uri_for( 'URI', \@ARGS ). At this time, there is no
361 way to pass query values equivalent to $c->uri_for( 'URI', \@ARGS,
362 \%QUERY_VALUES ).
363
364 The second codeword that is being replaced is __path_to( @DIRS )__. Any
365 instance is replaced with the result of passing the DIRS arguments to
366 "path_to" in Catalyst. Don't use qoutationmarks as they would become
367 part of the path.
368
369 Default value: 1
370
371 default_action_use_name
372
373 If set to a true value the action for the form will be set to the
374 currently called action name.
375
376 Default value: false.
377
378 default_action_use_path
379
380 If set to a true value the action for the form will be set to the
381 currently called action path. The action path includes concurrent to
382 action name additioal parameters which were code inside the path.
383
384 Default value: false.
385
386 Example:
387
388 action: /foo/bar
389 called uri contains: /foo/bar/1
390
391 # default_action_use_name => 1 leads to:
392 $form->action = /foo/bar
393
394 # default_action_use_path => 1 leads to:
395 $form->action = /foo/bar/1
396
397 model_stash
398
399 Arguments: \%stash_keys_to_model_names
400
401 Used to place Catalyst models on the form stash.
402
403 If it's being used to make a DBIx::Class schema available for
404 "options_from_model" in HTML::FormFu::Model::DBIC, for Select and other
405 Group-type elements - then the hash-key must be schema. For example, if
406 your schema model class is MyApp::Model::MySchema, you would set
407 model_stash like so:
408
409 <Controller::HTML::FormFu>
410 <model_stash>
411 schema MySchema
412 </model_stash>
413 </Controller::HTML::FormFu>
414
415 context_stash
416
417 To allow your form validation packages, etc, access to the catalyst
418 context, a weakened reference of the context is copied into the form's
419 stash.
420
421 $form->stash->{context};
422
423 This setting allows you to change the key name used in the form stash.
424
425 Default value: context
426
427 languages_from_context
428
429 If you're using a L10N / I18N plugin such as Catalyst::Plugin::I18N
430 which provides a languages method that returns a list of valid
431 languages to use for the currect request - and you want to use formfu's
432 built-in I18N packages, then setting "languages_from_context"
433
434 localize_from_context
435
436 If you're using a L10N / I18N plugin such as Catalyst::Plugin::I18N
437 which provides it's own localize method, you can set
438 localize_from_context to use that method for formfu's localization.
439
440 request_token_enable
441
442 If true, adds an instance of HTML::FormFu::Plugin::RequestToken to
443 every form, to stop accidental double-submissions of data and to
444 prevent CSRF attacks.
445
446 request_token_field_name
447
448 Defaults to _token.
449
450 request_token_session_key
451
452 Defaults to __token.
453
454 request_token_expiration_time
455
456 Defaults to 3600.
457
458 DISCONTINUED CONFIG SETTINGS
459
460 config_file_ext
461
462 Support for this has now been removed. Config files are now searched
463 for, with any file extension supported by Config::Any.
464
465 config_file_path
466
467 Support for this has now been removed. Use
468 {constructor}{config_file_path} instead.
469
470 CAVEATS
471
472 When using the Form action attribute to create an empty form, you must
473 call $form->process after populating the form. However, you don't need
474 to pass any arguments to process, as the Catalyst request object will
475 have automatically been set in $form->query.
476
477 When using the FormConfig and FormMethod action attributes, if you make
478 any modifications to the form, such as adding or changing it's
479 elements, you must call $form->process before rendering the form.
480
481 AUTHORS
482
483 * Carl Franks <[email protected]>
484
485 * Nigel Metheringham <[email protected]>
486
487 * Dean Hamstead <[email protected]>
488
489 COPYRIGHT AND LICENSE
490
491 This software is copyright (c) 2007-2018 by Carl Franks / Nigel
492 Metheringham / Dean Hamstead.
493
494 This is free software; you can redistribute it and/or modify it under
495 the same terms as the Perl 5 programming language system itself.
496
497 SUPPORT
498
499 Perldoc
500
501 You can find documentation for this module with the perldoc command.
502
503 perldoc Catalyst::Controller::HTML::FormFu
504
505 Websites
506
507 The following websites have more information about this module, and may
508 be of help to you. As always, in addition to those websites please use
509 your favorite search engine to discover more resources.
510
511 * MetaCPAN
512
513 A modern, open-source CPAN search engine, useful to view POD in HTML
514 format.
515
516 http://metacpan.org/release/Catalyst-Controller-HTML-FormFu
517
518 * Search CPAN
519
520 The default CPAN search engine, useful to view POD in HTML format.
521
522 http://search.cpan.org/dist/Catalyst-Controller-HTML-FormFu
523
524 * RT: CPAN's Bug Tracker
525
526 The RT ( Request Tracker ) website is the default bug/issue tracking
527 system for CPAN.
528
529 https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Controller-HTML-FormFu
530
531 * AnnoCPAN
532
533 The AnnoCPAN is a website that allows community annotations of Perl
534 module documentation.
535
536 http://annocpan.org/dist/Catalyst-Controller-HTML-FormFu
537
538 * CPAN Ratings
539
540 The CPAN Ratings is a website that allows community ratings and
541 reviews of Perl modules.
542
543 http://cpanratings.perl.org/d/Catalyst-Controller-HTML-FormFu
544
545 * CPAN Forum
546
547 The CPAN Forum is a web forum for discussing Perl modules.
548
549 http://cpanforum.com/dist/Catalyst-Controller-HTML-FormFu
550
551 * CPANTS
552
553 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
554 of a distribution.
555
556 http://cpants.cpanauthors.org/dist/Catalyst-Controller-HTML-FormFu
557
558 * CPAN Testers
559
560 The CPAN Testers is a network of smokers who run automated tests on
561 uploaded CPAN distributions.
562
563 http://www.cpantesters.org/distro/C/Catalyst-Controller-HTML-FormFu
564
565 * CPAN Testers Matrix
566
567 The CPAN Testers Matrix is a website that provides a visual overview
568 of the test results for a distribution on various Perls/platforms.
569
570 http://matrix.cpantesters.org/?dist=Catalyst-Controller-HTML-FormFu
571
572 * CPAN Testers Dependencies
573
574 The CPAN Testers Dependencies is a website that shows a chart of the
575 test results of all dependencies for a distribution.
576
577 http://deps.cpantesters.org/?module=Catalyst::Controller::HTML::FormFu
578
579 Bugs / Feature Requests
580
581 Please report any bugs or feature requests by email to
582 bug-catalyst-controller-html-formfu at rt.cpan.org, or through the web
583 interface at
584 https://rt.cpan.org/Public/Bug/Report.html?Queue=Catalyst-Controller-HTML-FormFu.
585 You will be automatically notified of any progress on the request by
586 the system.
587
588 Source Code
589
590 The code is open to the world, and available for you to hack on. Please
591 feel free to browse it and play with it, or whatever. If you want to
592 contribute patches, please send me a diff or prod me to pull from your
593 repository :)
594
595 https://github.com/FormFu/Catalyst-Controller-HTML-FormFu
596
597 git clone https://github.com/FormFu/Catalyst-Controller-HTML-FormFu.git
598
599 CONTRIBUTORS
600
601 * Aran Deltac <[email protected]>
602
603 * bricas <[email protected]>
604
605 * dandv <[email protected]>
606
607 * fireartist <[email protected]>
608
609 * lestrrat <[email protected]>
610
611 * marcusramberg <[email protected]>
612
613 * mariominati <[email protected]>
614
615 * Moritz Onken <[email protected]>
616
617 * Moritz Onken <[email protected]>
618
619 * Nigel Metheringham <[email protected]>
620
621 * omega <[email protected]>
622
623 * Petr Písař <[email protected]>
624