1HTML::FormFu(3)       User Contributed Perl Documentation      HTML::FormFu(3)
2
3
4

NAME

6       HTML::FormFu - HTML Form Creation, Rendering and Validation Framework
7

VERSION

9       version 2.07
10

SYNOPSIS

12       Note: These examples make use of HTML::FormFu::Model::DBIC. As of
13       "HTML::FormFu" v02.005, the HTML::FormFu::Model::DBIC module is not
14       bundled with "HTML::FormFu" and is available in a stand-alone
15       distribution.
16
17           use HTML::FormFu;
18
19           my $form = HTML::FormFu->new;
20
21           $form->load_config_file('form.yml');
22
23           $form->process( $cgi_query );
24
25           if ( $form->submitted_and_valid ) {
26               # do something with $form->params
27           }
28           else {
29               # display the form
30               $template->param( form => $form );
31           }
32
33       If you're using Catalyst, a more suitable example might be:
34
35           package MyApp::Controller::User;
36           use Moose;
37           extends 'Catalyst::Controller::HTML::FormFu';
38
39           sub user : Chained CaptureArgs(1) {
40               my ( $self, $c, $id ) = @_;
41
42               my $rs = $c->model('Schema')->resultset('User');
43
44               $c->stash->{user} = $rs->find( $id );
45
46               return;
47           }
48
49           sub edit : Chained('user') Args(0) FormConfig {
50               my ( $self, $c ) = @_;
51
52               my $form = $c->stash->{form};
53               my $user = $c->stash->{user};
54
55               if ( $form->submitted_and_valid ) {
56
57                   $form->model->update( $user );
58
59                   $c->res->redirect( $c->uri_for( "/user/$id" ) );
60                   return;
61               }
62
63               $form->model->default_values( $user )
64                   if ! $form->submitted;
65
66           }
67
68       Note: Because "process" is automatically called for you by the Catalyst
69       controller; if you make any modifications to the form within your
70       action method, such as adding or changing elements, adding constraints,
71       etc; you must call "process" again yourself before using
72       "submitted_and_valid", any of the methods listed under "SUBMITTED FORM
73       VALUES AND ERRORS" or "MODIFYING A SUBMITTED FORM", or rendering the
74       form.
75
76       Here's an example of a config file to create a basic login form (all
77       examples here are YAML, but you can use any format supported by
78       Config::Any), you can also create forms directly in your perl code,
79       rather than using an external config file.
80
81           ---
82           action: /login
83           indicator: submit
84           auto_fieldset: 1
85
86           elements:
87             - type: Text
88               name: user
89               constraints:
90                 - Required
91
92             - type: Password
93               name: pass
94               constraints:
95                 - Required
96
97             - type: Submit
98               name: submit
99
100           constraints:
101             - SingleValue
102

DESCRIPTION

104       HTML::FormFu is a HTML form framework which aims to be as easy as
105       possible to use for basic web forms, but with the power and flexibility
106       to do anything else you might want to do (as long as it involves
107       forms).
108
109       You can configure almost any part of formfu's behaviour and output. By
110       default formfu renders "XHTML 1.0 Strict" compliant markup, with as
111       little extra markup as possible, but with sufficient CSS class names to
112       allow for a wide-range of output styles to be generated by changing
113       only the CSS.
114
115       All methods listed below (except "new") can either be called as a
116       normal method on your $form object, or as an option in your config
117       file. Examples will mainly be shown in YAML config syntax.
118
119       This documentation follows the convention that method arguments
120       surrounded by square brackets "[]" are optional, and all other
121       arguments are required.
122

BUILDING A FORM

124   new
125       Arguments: [\%options]
126
127       Return Value: $form
128
129       Create a new HTML::FormFu object.
130
131       Any method which can be called on the HTML::FormFu object may instead
132       be passed as an argument to "new".
133
134           my $form = HTML::FormFu->new({
135               action        => '/search',
136               method        => 'GET',
137               auto_fieldset => 1,
138           });
139
140   load_config_file
141       Arguments: $filename
142
143       Arguments: \@filenames
144
145       Return Value: $form
146
147       Accepts a filename or list of file names, whose filetypes should be of
148       any format recognized by Config::Any.
149
150       The content of each config file is passed to "populate", and so are
151       added to the form.
152
153       "load_config_file" may be called in a config file itself, so as to
154       allow common settings to be kept in a single config file which may be
155       loaded by any form.
156
157           ---
158           load_config_file:
159             - file1
160             - file2
161
162       YAML multiple documents within a single file. The document start marker
163       is a line containing 3 dashes. Multiple documents will be applied in
164       order, just as if multiple filenames had been given.
165
166       In the following example, multiple documents are taken advantage of to
167       load another config file after the elements are added. (If this were a
168       single document, the "load_config_file" would be called before
169       "elements", regardless of its position in the file).
170
171           ---
172           elements:
173             - name: one
174             - name: two
175
176           ---
177           load_config_file: ext.yml
178
179       Relative paths are resolved from the "config_file_path" directory if it
180       is set, otherwise from the current working directory.
181
182       See "BEST PRACTICES" for advice on organising config files.
183
184   config_callback
185       Arguments: \%options
186
187       If defined, the arguments are used to create a Data::Visitor::Callback
188       object during "load_config_file" which may be used to pre-process the
189       config before it is sent to "populate".
190
191       For example, the code below adds a callback to a form that will
192       dynamically alter any config value ending in ".yml" to end in ".yaml"
193       when you call "load_config_file":
194
195           $form->config_callback({
196             plain_value => sub {
197               my( $visitor, $data ) = @_;
198               s/\.yml/.yaml/;
199             }
200           });
201
202       Default Value: not defined
203
204       This method is a special 'inherited accessor', which means it can be
205       set on the form, a block element or a single element. When the value is
206       read, if no value is defined it automatically traverses the element's
207       hierarchy of parents, through any block elements and up to the form,
208       searching for a defined value.
209
210   populate
211       Arguments: \%options
212
213       Return Value: $form
214
215       Each option key/value passed may be any HTML::FormFu method-name and
216       arguments.
217
218       Provides a simple way to set multiple values, or add multiple elements
219       to a form with a single method-call.
220
221       Attempts to call the method-names in a semi-intelligent order (see the
222       source of populate() in "HTML::FormFu::ObjectUtil" for details).
223
224   default_values
225       Arguments: \%defaults
226
227       Return Value: $form
228
229       Set multiple field's default values from a single hash-ref.
230
231       The hash-ref's keys correspond to a form field's name, and the value is
232       passed to the field's default method.
233
234       This should be called after all fields have been added to the form, and
235       before "process" is called (otherwise, call "process" again before
236       rendering the form).
237
238   config_file_path
239       Arguments: $directory_name
240
241       "config_file_path" defines where configuration files will be searched
242       for, if an absolute path is not given to "load_config_file".
243
244       Default Value: not defined
245
246       This method is a special 'inherited accessor', which means it can be
247       set on the form, a block element or a single element. When the value is
248       read, if no value is defined it automatically traverses the element's
249       hierarchy of parents, through any block elements and up to the form,
250       searching for a defined value.
251
252       Is an inheriting accessor.
253
254   indicator
255       Arguments: $field_name
256
257       Arguments: \&coderef
258
259       If "indicator" is set to a fieldname, "submitted" will return true if a
260       value for that fieldname was submitted.
261
262       If "indicator" is set to a code-ref, it will be called as a subroutine
263       with the two arguments $form and $query, and its return value will be
264       used as the return value for "submitted".
265
266       If "indicator" is not set, "submitted" will return true if a value for
267       any known fieldname was submitted.
268
269   auto_fieldset
270       Arguments: 1
271
272       Arguments: \%options
273
274       Return Value: $fieldset
275
276       This setting is suitable for most basic forms, and means you can
277       generally ignore adding fieldsets yourself.
278
279       Calling "$form->auto_fieldset(1)" immediately adds a fieldset element
280       to the form. Thereafter, "$form->elements()" will add all elements
281       (except fieldsets) to that fieldset, rather than directly to the form.
282
283       To be specific, the elements are added to the last fieldset on the
284       form, so if you add another fieldset, any further elements will be
285       added to that fieldset.
286
287       Also, you may pass a hashref to auto_fieldset(), and this will be used
288       to set defaults for the first fieldset created.
289
290       A few examples and their output, to demonstrate:
291
292       2 elements with no fieldset.
293
294           ---
295           elements:
296             - type: Text
297               name: foo
298             - type: Text
299               name: bar
300
301           <form action="" method="post">
302             <div class="text">
303               <input name="foo" type="text" />
304             </div>
305             <div class="text">
306               <input name="bar" type="text" />
307             </div>
308           </form>
309
310       2 elements with an "auto_fieldset".
311
312           ---
313           auto_fieldset: 1
314           elements:
315             - type: Text
316               name: foo
317             - type: Text
318               name: bar
319
320           <form action="" method="post">
321             <fieldset>
322               <div class="text">
323                 <input name="foo" type="text" />
324               </div>
325               <div class="text">
326                 <input name="bar" type="text" />
327               </div>
328             </fieldset>
329           </form>
330
331       The 3rd element is within a new fieldset
332
333           ---
334           auto_fieldset: { id: fs }
335           elements:
336             - type: Text
337               name: foo
338             - type: Text
339               name: bar
340             - type: Fieldset
341             - type: Text
342               name: baz
343
344           <form action="" method="post">
345             <fieldset id="fs">
346               <div class="text">
347                 <input name="foo" type="text" />
348               </div>
349               <div class="text">
350                 <input name="bar" type="text" />
351               </div>
352             </fieldset>
353             <fieldset>
354               <div class="text">
355                 <input name="baz" type="text" />
356               </div>
357             </fieldset>
358           </form>
359
360       Because of this behaviour, if you want nested fieldsets you will have
361       to add each nested fieldset directly to its intended parent.
362
363           my $parent = $form->get_element({ type => 'Fieldset' });
364
365           $parent->element('fieldset');
366
367   form_error_message
368       Arguments: $string
369
370       Normally, input errors cause an error message to be displayed alongside
371       the appropriate form field. If you'd also like a general error message
372       to be displayed at the top of the form, you can set the message with
373       "form_error_message".
374
375       To set the CSS class for the message, see "form_error_message_class".
376
377       To change the markup used to display the message, edit the
378       "form_error_message" template file. See "render_method".
379
380       Is an output accessor.
381
382   force_error_message
383       If true, forces the "form_error_message" to be displayed even if there
384       are no field errors.
385
386   default_args
387       Arguments: \%defaults
388
389       Set defaults which will be added to every element, constraint, etc. of
390       the given type which is subsequently added to the form.
391
392       For example, to make every "Text" element automatically have a size of
393       10, and make every "Strftime" deflator automatically get its strftime
394       set to "%d/%m/%Y":
395
396           default_args:
397               elements:
398                   Text:
399                       size: 10
400               deflators:
401                   Strftime:
402                       strftime: '%d/%m/%Y'
403
404       An example to make all DateTime elements automatically get an
405       appropriate Strftime deflator and a DateTime inflator:
406
407           default_args:
408               elements:
409                   DateTime:
410                       deflators:
411                           type: Strftime
412                           strftime: '%d-%m-%Y'
413                       inflators:
414                           type: DateTime
415                           parser:
416                               strptime: '%d-%m-%Y'
417
418       Pseudo types
419
420       As a special case, you can also use the "elements" keys "Block",
421       "Field" and "Input" to match any element which inherits from
422       HTML::FormFu::Element::Block or which "does"
423       HTML::FormFu::Role::Element::Field or
424       HTML::FormFu::Role::Element::Input.
425
426       Alternatives
427
428       Each "elements" key can contain an "any" list using the "|" divider:
429       e.g.
430
431           # apply the given class to any Element of type Password or Button
432           default_args:
433               elements:
434                   'Password|Button':
435                       attrs:
436                           class: novalidate
437
438       Match ancestor
439
440       Each "elements" key list can contain a type starting with "+" to only
441       match elements with an ancestor of the given type: e.g.
442
443           # only apple the given class to an Input field within a Multi block
444           default_args:
445               elements:
446                   'Input|+Multi':
447                       attrs:
448                           class: novalidate
449
450       Don't match ancestor
451
452       Each "elements" key list can contain a type starting with "-" to only
453       match elements who do not have an ancestor of the given type: e.g.
454
455           # apply the given class only to Input fields that are not in a Multi block
456           default_args:
457               elements:
458                   'Input|-Multi':
459                       attrs:
460                           clasS: validate
461
462       Order
463
464       The arguments are applied in least- to most-specific order: "Block",
465       "Field", "Input", $type. Within each of these, arguments are applied in
466       order of shortest-first to longest-last.
467
468       The "type" key must match the value returned by "type", e.g.  "type" in
469       HTML::FormFu::Element. If, for example, you have a custom element
470       outside of the "HTML::FormFu::Element::*" namespace, which you load via
471       "$form->element({ type => '+My::Custom::Element' })", the key given to
472       "default_args" should not include the leading "+", as that is stripped-
473       out of the returned "type()" value. Example:
474
475           # don't include the leading '+' here
476           default_args:
477               elements:
478                   'My::Custom::Element':
479                       attrs:
480                           class: whatever
481
482           # do include the leading '+' here
483           elements:
484               - type: +My::Custom::Element
485
486       Clashes
487
488       "default_args" generates a single hashref to pass to "populate",
489       merging arguments for each type in turn - meaning "populate" is only
490       called once in total - not once for each type.  Because scalar values
491       are not merged - this means later values will override earlier values:
492       e.g.
493
494           # Normally, calling $field->add_attrs({ class => 'input' })
495           # then calling      $field->add_attrs({ class => 'not-in-multi' })
496           # would result in both values being retained:
497           #           class="input not-in-multi"
498           #
499           # However, default_args() creates a single data-structure to pass once
500           # to populate(), so any scalar values will overwrite earlier ones
501           # before they reach populate().
502           #
503           # The below example would result in the longest-matching key
504           # overwriting any others:
505           #           class="not-in-multi"
506           #
507           default_args:
508               elements:
509                   Input:
510                       add_attrs:
511                           class: input
512                   'Input:-Multi':
513                       add_attrs:
514                           class: not-in-multi
515
516       Strictness
517
518       Note: Unlike the proper methods which have aliases, for example
519       "elements" which is an alias for "element" - the keys given to
520       "default_args" must be of the plural form, e.g.:
521
522           default_args:
523               elements:          {}
524               deflators:         {}
525               filters:           {}
526               constraints:       {}
527               inflators:         {}
528               validators:        {}
529               transformers:      {}
530               output_processors: {}
531
532   javascript
533       If set, the contents will be rendered within a "script" tag, inside the
534       top of the form.
535
536   javascript_src
537       Arguments: $url
538
539       Arguments: \@urls
540
541       Adds a "script" tag for each URL, immediately before any "javascript"
542       section.
543
544   stash
545       Arguments: [\%private_stash]
546
547       Return Value: \%stash
548
549       Provides a hash-ref in which you can store any data you might want to
550       associate with the form.
551
552           ---
553           stash:
554             foo: value
555             bar: value
556
557   elements
558   element
559       Arguments: $type
560
561       Arguments: \%options
562
563       Return Value: $element
564
565       Arguments: \@arrayref_of_types_or_options
566
567       Return Value: @elements
568
569       Adds a new element to the form. See "CORE FORM FIELDS" in
570       HTML::FormFu::Element and "OTHER CORE ELEMENTS" in
571       HTML::FormFu::Element for a list of core elements.
572
573       If you want to load an element from a namespace other than
574       "HTML::FormFu::Element::", you can use a fully qualified package-name
575       by prefixing it with "+".
576
577           ---
578           elements:
579             - type: +MyApp::CustomElement
580               name: foo
581
582       If a "type" is not provided in the "\%options", the default "Text" will
583       be used.
584
585       "element" is an alias for "elements".
586
587   deflators
588   deflator
589       Arguments: $type
590
591       Arguments: \%options
592
593       Return Value: $deflator
594
595       Arguments: \@arrayref_of_types_or_options
596
597       Return Value: @deflators
598
599       A deflator may be associated with any form field, and allows you to
600       provide $field->default with a value which may be an object.
601
602       If an object doesn't stringify to a suitable value for display, the
603       deflator can ensure that the form field receives a suitable string
604       value instead.
605
606       See "CORE DEFLATORS" in HTML::FormFu::Deflator for a list of core
607       deflators.
608
609       If a "name" attribute isn't provided, a new deflator is created for and
610       added to every field on the form.
611
612       If you want to load a deflator in a namespace other than
613       "HTML::FormFu::Deflator::", you can use a fully qualified package-name
614       by prefixing it with "+".
615
616       "deflator" is an alias for "deflators".
617
618   insert_before
619       Arguments: $new_element, $existing_element
620
621       Return Value: $new_element
622
623       The 1st argument must be the element you want added, the 2nd argument
624       must be the existing element that the new element should be placed
625       before.
626
627           my $new = $form->element(\%specs);
628
629           my $position = $form->get_element({ type => $type, name => $name });
630
631           $form->insert_before( $new, $position );
632
633       In the first line of the above example, the $new element is initially
634       added to the end of the form. However, the "insert_before" method
635       reparents the $new element, so it will no longer be on the end of the
636       form. Because of this, if you try to copy an element from one form to
637       another, it will 'steal' the element, instead of copying it. In this
638       case, you must use "clone":
639
640           my $new = $form1->get_element({ type => $type1, name => $name1 })
641                           ->clone;
642
643           my $position = $form2->get_element({ type => $type2, name => $name2 });
644
645           $form2->insert_before( $new, $position );
646
647   insert_after
648       Arguments: $new_element, $existing_element
649
650       Return Value: $new_element
651
652       The 1st argument must be the element you want added, the 2nd argument
653       must be the existing element that the new element should be placed
654       after.
655
656           my $new = $form->element(\%specs);
657
658           my $position = $form->get_element({ type => $type, name => $name });
659
660           $form->insert_after( $new, $position );
661
662       In the first line of the above example, the $new element is initially
663       added to the end of the form. However, the "insert_after" method
664       reparents the $new element, so it will no longer be on the end of the
665       form. Because of this, if you try to copy an element from one form to
666       another, it will 'steal' the element, instead of copying it. In this
667       case, you must use "clone":
668
669           my $new = $form1->get_element({ type => $type1, name => $name1 })
670                           ->clone;
671
672           my $position = $form2->get_element({ type => $type2, name => $name2 });
673
674           $form2->insert_after( $new, $position );
675
676   remove_element
677       Arguments: $element
678
679       Return Value: $element
680
681       Removes the $element from the form or block's array of children.
682
683           $form->remove_element( $element );
684
685       The orphaned element cannot be usefully used for anything until it is
686       re-attached to a form or block with "insert_before" or "insert_after".
687

FORM LOGIC AND VALIDATION

689       HTML::FormFu provides several stages for what is traditionally
690       described as validation. These are:
691
692       HTML::FormFu::Filter
693       HTML::FormFu::Constraint
694       HTML::FormFu::Inflator
695       HTML::FormFu::Validator
696       HTML::FormFu::Transformer
697
698       The first stage, the filters, allow for cleanup of user-input, such as
699       encoding, or removing leading/trailing whitespace, or removing non-
700       digit characters from a creditcard number.
701
702       All of the following stages allow for more complex processing, and each
703       of them have a mechanism to allow exceptions to be thrown, to represent
704       input errors. In each stage, all form fields must be processed without
705       error for the next stage to proceed. If there were any errors, the form
706       should be re-displayed to the user, to allow them to input correct
707       values.
708
709       Constraints are intended for low-level validation of values, such as
710       "is this an integer?", "is this value within bounds?" or "is this a
711       valid email address?".
712
713       Inflators are intended to allow a value to be turned into an
714       appropriate object. The resulting object will be passed to subsequent
715       Validators and Transformers, and will also be returned by "params" and
716       "param".
717
718       Validators are intended for higher-level validation, such as business-
719       logic and database constraints such as "is this username unique?".
720       Validators are only run if all Constraints and Inflators have run
721       without errors. It is expected that most Validators will be
722       application-specific, and so each will be implemented as a separate
723       class written by the HTML::FormFu user.
724
725   filters
726   filter
727       Arguments: $type
728
729       Arguments: \%options
730
731       Return Value: $filter
732
733       Arguments: \@arrayref_of_types_or_options
734
735       Return Value: @filters
736
737       If you provide a "name" or "names" value, the filter will be added to
738       just that named field.  If you do not provide a "name" or "names"
739       value, the filter will be added to all fields already attached to the
740       form.
741
742       See "CORE FILTERS" in HTML::FormFu::Filter for a list of core filters.
743
744       If you want to load a filter in a namespace other than
745       "HTML::FormFu::Filter::", you can use a fully qualified package-name by
746       prefixing it with "+".
747
748       "filter" is an alias for "filters".
749
750   constraints
751   constraint
752       Arguments: $type
753
754       Arguments: \%options
755
756       Return Value: $constraint
757
758       Arguments: \@arrayref_of_types_or_options
759
760       Return Value: @constraints
761
762       See "CORE CONSTRAINTS" in HTML::FormFu::Constraint for a list of core
763       constraints.
764
765       If a "name" attribute isn't provided, a new constraint is created for
766       and added to every field on the form.
767
768       If you want to load a constraint in a namespace other than
769       "HTML::FormFu::Constraint::", you can use a fully qualified package-
770       name by prefixing it with "+".
771
772       "constraint" is an alias for "constraints".
773
774   inflators
775   inflator
776       Arguments: $type
777
778       Arguments: \%options
779
780       Return Value: $inflator
781
782       Arguments: \@arrayref_of_types_or_options
783
784       Return Value: @inflators
785
786       See "CORE INFLATORS" in HTML::FormFu::Inflator for a list of core
787       inflators.
788
789       If a "name" attribute isn't provided, a new inflator is created for and
790       added to every field on the form.
791
792       If you want to load an inflator in a namespace other than
793       "HTML::FormFu::Inflator::", you can use a fully qualified package-name
794       by prefixing it with "+".
795
796       "inflator" is an alias for "inflators".
797
798   validators
799   validator
800       Arguments: $type
801
802       Arguments: \%options
803
804       Return Value: $validator
805
806       Arguments: \@arrayref_of_types_or_options
807
808       Return Value: @validators
809
810       See "CORE VALIDATORS" in HTML::FormFu::Validator for a list of core
811       validators.
812
813       If a "name" attribute isn't provided, a new validator is created for
814       and added to every field on the form.
815
816       If you want to load a validator in a namespace other than
817       "HTML::FormFu::Validator::", you can use a fully qualified package-name
818       by prefixing it with "+".
819
820       "validator" is an alias for "validators".
821
822   transformers
823   transformer
824       Arguments: $type
825
826       Arguments: \%options
827
828       Return Value: $transformer
829
830       Arguments: \@arrayref_of_types_or_options
831
832       Return Value: @transformers
833
834       See "CORE TRANSFORMERS" in HTML::FormFu::Transformer for a list of core
835       transformers.
836
837       If a "name" attribute isn't provided, a new transformer is created for
838       and added to every field on the form.
839
840       If you want to load a transformer in a namespace other than
841       "HTML::FormFu::Transformer::", you can use a fully qualified package-
842       name by prefixing it with "+".
843
844       "transformer" is an alias for "transformers".
845

CHANGING DEFAULT BEHAVIOUR

847   render_processed_value
848       The default behaviour when re-displaying a form after a submission, is
849       that the field contains the original unchanged user-submitted value.
850
851       If "render_processed_value" is true, the field value will be the final
852       result after all Filters, Inflators and Transformers have been run.
853       Deflators will also be run on the value.
854
855       If you set this on a field with an Inflator, but without an equivalent
856       Deflator, you should ensure that the Inflators stringify back to a
857       usable value, so as not to confuse / annoy the user.
858
859       Default Value: false
860
861       This method is a special 'inherited accessor', which means it can be
862       set on the form, a block element or a single element. When the value is
863       read, if no value is defined it automatically traverses the element's
864       hierarchy of parents, through any block elements and up to the form,
865       searching for a defined value.
866
867       Is an inheriting accessor.
868
869   force_errors
870       Force a constraint to fail, regardless of user input.
871
872       If this is called at runtime, after the form has already been
873       processed, you must called "process" in HTML::FormFu again before
874       redisplaying the form to the user.
875
876       Default Value: false
877
878       This method is a special 'inherited accessor', which means it can be
879       set on the form, a block element, an element or a single constraint.
880       When the value is read, if no value is defined it automatically
881       traverses the element's hierarchy of parents, through any block
882       elements and up to the form, searching for a defined value.
883
884       Is an inheriting accessor.
885
886   params_ignore_underscore
887       If true, causes "params", "param" and "valid" to ignore any fields
888       whose name starts with an underscore "_".
889
890       The field is still processed as normal, and errors will cause
891       "submitted_and_valid" to return false.
892
893       Default Value: false
894

FORM ATTRIBUTES

896       All attributes are added to the rendered form's start tag.
897
898   attributes
899           # Example
900           ---
901           attributes:
902             id: form
903             class: fancy_form
904
905       Is an attribute accessor.
906
907   id
908       Is an attribute short-cut.
909
910   action
911       Default Value: ""
912
913       Get or set the action associated with the form. The default is no
914       action, which causes most browsers to submit to the current URI.
915
916       Is an attribute short-cut.
917
918   enctype
919       Get or set the encoding type of the form. Valid values are
920       "application/x-www-form-urlencoded" and "multipart/form-data".
921
922       If the form contains a File element, the enctype is automatically set
923       to "multipart/form-data".
924
925       Is an attribute short-cut.
926
927   method
928       Default Value: "post"
929
930       Get or set the method used to submit the form. Can be set to either
931       "post" or "get".
932
933       Is an attribute short-cut.
934
935   title
936       Get or set the form's title attribute.
937
938       Is an attribute short-cut.
939

CSS CLASSES

941   form_error_message_class
942       Class attribute for the error message displayed at the top of the form.
943
944       See "form_error_message"
945

LOCALIZATION

947   languages
948       Arguments: [\@languages]
949
950       A list of languages which will be passed to the localization object.
951
952       Default Value: ['en']
953
954   localize_class
955       Arguments: [$class_name]
956
957       Classname to be used for the default localization object.
958
959       Default Value: 'HTML::FormFu::I18N'
960
961   localize
962   loc
963       Arguments: [$key, @arguments]
964
965       Compatible with the "maketext" method in Locale::Maketext.
966
967   locale
968       Arguments: $locale
969
970       Currently only used by HTML::FormFu::Deflator::FormatNumber and
971       HTML::FormFu::Filter::FormatNumber.
972
973       This method is a special 'inherited accessor', which means it can be
974       set on the form, a block element or a single element. When the value is
975       read, if no value is defined it automatically traverses the element's
976       hierarchy of parents, through any block elements and up to the form,
977       searching for a defined value.
978
979       Is an inheriting accessor.
980

PROCESSING A FORM

982   query
983       Arguments: [$query_object]
984
985       Arguments: \%params
986
987       Provide a CGI compatible query object or a hash-ref of submitted
988       names/values. Alternatively, the query object can be passed directly to
989       the "process" object.
990
991   query_type
992       Arguments: [$query_type]
993
994       Set which module is being used to provide the "query".
995
996       The Catalyst::Controller::HTML::FormFu automatically sets this to
997       "Catalyst".
998
999       Valid values are "CGI", "Catalyst" and "CGI::Simple".
1000
1001       Default Value: 'CGI'
1002
1003   process
1004       Arguments: [$query_object]
1005
1006       Arguments: [\%params]
1007
1008       Process the provided query object or input values. "process" must be
1009       called before calling any of the methods listed under "SUBMITTED FORM
1010       VALUES AND ERRORS" and "MODIFYING A SUBMITTED FORM".
1011
1012       "process" must also be called at least once before printing the form or
1013       calling "render" or "render_data".
1014
1015       Note to users of Catalyst::Controller::HTML::FormFu: Because "process"
1016       is automatically called for you by the Catalyst controller; if you make
1017       any modifications to the form within your action method, such as adding
1018       or changing elements, adding constraints, etc; you must call "process"
1019       again yourself before using "submitted_and_valid", any of the methods
1020       listed under "SUBMITTED FORM VALUES AND ERRORS" or "MODIFYING A
1021       SUBMITTED FORM", or rendering the form.
1022

SUBMITTED FORM VALUES AND ERRORS

1024   submitted
1025       Returns true if the form has been submitted. See "indicator" for
1026       details on how this is computed.
1027
1028   submitted_and_valid
1029       Shorthand for "$form->submitted && !$form->has_errors"
1030
1031   params
1032       Return Value: \%params
1033
1034       Returns a hash-ref of all valid input for which there were no errors.
1035
1036   param_value
1037       Arguments: $field_name
1038
1039       A more reliable, recommended version of "param". Guaranteed to always
1040       return a single value, regardless of whether it's called in list
1041       context or not. If multiple values were submitted, this only returns
1042       the first value. If the value is invalid or the form was not submitted,
1043       it returns "undef". This makes it suitable for use in list context,
1044       where a single value is required.
1045
1046           $db->update({
1047               name    => $form->param_value('name'),
1048               address => $form->param_value('address),
1049           });
1050
1051   param_array
1052       Arguments: $field_name
1053
1054       Guaranteed to always return an array-ref of values, regardless of
1055       context and regardless of whether multiple values were submitted or
1056       not. If the value is invalid or the form was not submitted, it returns
1057       an empty array-ref.
1058
1059   param_list
1060       Arguments: $field_name
1061
1062       Guaranteed to always return a list of values, regardless of context. If
1063       the value is invalid or the form was not submitted, it returns an empty
1064       list.
1065
1066   param
1067       Arguments: [$field_name]
1068
1069       Return Value: $input_value
1070
1071       Return Value: @valid_names
1072
1073       No longer recommended for use, as its behaviour is hard to predict. Use
1074       "param_value", "param_array" or "param_list" instead.
1075
1076       A (readonly) method similar to that of CGI's.
1077
1078       If a field name is given, in list-context returns any valid values
1079       submitted for that field, and in scalar-context returns only the first
1080       of any valid values submitted for that field.
1081
1082       If no argument is given, returns a list of all valid input field names
1083       without errors.
1084
1085       Passing more than 1 argument is a fatal error.
1086
1087   valid
1088       Arguments: [$field_name]
1089
1090       Return Value: @valid_names
1091
1092       Return Value: $bool
1093
1094       If a field name if given, returns "true" if that field had no errors
1095       and "false" if there were errors.
1096
1097       If no argument is given, returns a list of all valid input field names
1098       without errors.
1099
1100   has_errors
1101       Arguments: [$field_name]
1102
1103       Return Value: @names
1104
1105       Return Value: $bool
1106
1107       If a field name if given, returns "true" if that field had errors and
1108       "false" if there were no errors.
1109
1110       If no argument is given, returns a list of all input field names with
1111       errors.
1112
1113   get_errors
1114       Arguments: [%options]
1115
1116       Arguments: [\%options]
1117
1118       Return Value: \@errors
1119
1120       Returns an array-ref of exception objects from all fields in the form.
1121
1122       Accepts both "name", "type" and "stage" arguments to narrow the
1123       returned results.
1124
1125           $form->get_errors({
1126               name  => 'foo',
1127               type  => 'Regex',
1128               stage => 'constraint'
1129           });
1130
1131   get_error
1132       Arguments: [%options]
1133
1134       Arguments: [\%options]
1135
1136       Return Value: $error
1137
1138       Accepts the same arguments as "get_errors", but only returns the first
1139       error found.
1140

MODEL / DATABASE INTERACTION

1142       See HTML::FormFu::Model for further details and available models.
1143
1144   default_model
1145       Arguments: $model_name
1146
1147       Default Value: 'DBIC'
1148
1149   model
1150       Arguments: [$model_name]
1151
1152       Return Value: $model
1153
1154   model_config
1155       Arguments: \%config
1156

MODIFYING A SUBMITTED FORM

1158   add_valid
1159       Arguments: $name, $value
1160
1161       Return Value: $value
1162
1163       The provided value replaces any current value for the named field. This
1164       value will be returned in subsequent calls to "params" and "param" and
1165       the named field will be included in calculations for "valid".
1166
1167   clear_errors
1168       Deletes all errors from a submitted form.
1169

RENDERING A FORM

1171   render
1172       Return Value: $string
1173
1174       You must call "process" once after building the form, and before
1175       calling "render".
1176
1177   start
1178       Return Value: $string
1179
1180       Returns the form start tag, and any output of "form_error_message" and
1181       "javascript".
1182
1183   end
1184       Return Value: $string
1185
1186       Returns the form end tag.
1187
1188   hidden_fields
1189       Return Value: $string
1190
1191       Returns all hidden form fields.
1192

PLUGIN SYSTEM

1194       "HTML::FormFu" provides a plugin-system that allows plugins to be
1195       easily added to a form or element, to change the default behaviour or
1196       output.
1197
1198       See HTML::FormFu::Plugin for details.
1199

ADVANCED CUSTOMISATION

1201       By default, formfu renders "XHTML 1.0 Strict" compliant markup, with as
1202       little extra markup as possible. Many hooks are provided to add
1203       programatically-generated CSS class names, to allow for a wide-range of
1204       output styles to be generated by changing only the CSS.
1205
1206       Basic customisation of the markup is possible via the layout and
1207       multi_layout methods.  This allows you to reorder the position of
1208       various parts of each field - such as the label, comment, error
1209       messages and the input tag - as well as inserting any other arbitrary
1210       tags you may wish.
1211
1212       If this is not sufficient, you can make completely personalise the
1213       markup by telling HTML::FormFu to use an external rendering engine,
1214       such as Template Toolkit or Template::Alloy.  See "render_method" and
1215       "tt_module" for details.
1216
1217       Even if you set HTML::FormFu to use Template::Toolkit to render, the
1218       forms, HTML::FormFu can still be used in conjunction with whichever
1219       other templating system you prefer to use for your own page layouts,
1220       whether it's HTML::Template: "<TMPL_VAR form>", Petal: "<form
1221       tal:replace="form"></form>" or Template::Magic: "<!-- {form} -->".
1222
1223       As of "HTML::FormFu v1.00", TT is no longer listed a required
1224       prerequisite - so you'll need to install it manually if you with to use
1225       the template files.
1226
1227   render_method
1228       Default Value: "string"
1229
1230       Can be set to "tt" to generate the form with external template files.
1231
1232       To customise the markup, you'll need a copy of the template files,
1233       local to your application. See "Installing the TT templates" in
1234       HTML::FormFu::Manual::Cookbook for further details.
1235
1236       You can customise the markup for a single element by setting that
1237       element's "render_method" to "tt", while the rest of the form uses the
1238       default "string" render-method. Note though, that if you try setting
1239       the form or a Block's "render_method" to "tt", and then set a child
1240       element's "render_method" to "string", that setting will be ignored,
1241       and the child elements will still use the "tt" render-method.
1242
1243           ---
1244           elements:
1245             - name: foo
1246               render_method: tt
1247               filename: custom_field
1248
1249             - name: bar
1250
1251           # in this example, 'foo' will use a custom template,
1252           # while bar will use the default 'string' rendering method
1253
1254       This method is a special 'inherited accessor', which means it can be
1255       set on the form, a block element or a single element. When the value is
1256       read, if no value is defined it automatically traverses the element's
1257       hierarchy of parents, through any block elements and up to the form,
1258       searching for a defined value.
1259
1260       Is an inheriting accessor.
1261
1262   filename
1263       Change the template filename used for the form.
1264
1265       Default Value: "form"
1266
1267   tt_args
1268       Arguments: [\%constructor_arguments]
1269
1270       Accepts a hash-ref of arguments passed to "render_method", which is
1271       called internally by "render".
1272
1273       Within tt_args, the keys "RELATIVE" and "RECURSION" are overridden to
1274       always be true, as these are a basic requirement for the Template
1275       engine.
1276
1277       The system directory containing HTML::FormFu's template files is always
1278       added to the end of "INCLUDE_PATH", so that the core template files
1279       will be found. You only need to set this yourself if you have your own
1280       copy of the template files for customisation purposes.
1281
1282       This method is a special 'inherited accessor', which means it can be
1283       set on the form, a block element or a single element. When the value is
1284       read, if no value is defined it automatically traverses the element's
1285       hierarchy of parents, through any block elements and up to the form,
1286       searching for a defined value.
1287
1288   add_tt_args
1289       Arguments: [\%constructor_arguments]
1290
1291       Ensures that the hash-ref argument is merged with any existing hash-ref
1292       value of "tt_args".
1293
1294   tt_module
1295       Default Value: Template
1296
1297       The module used when "render_method" is set to "tt". Should provide an
1298       interface compatible with Template.
1299
1300       This method is a special 'inherited accessor', which means it can be
1301       set on the form, a block element or a single element. When the value is
1302       read, if no value is defined it automatically traverses the element's
1303       hierarchy of parents, through any block elements and up to the form,
1304       searching for a defined value.
1305
1306   render_data
1307       Usually called implicitly by "render". Returns the data structure that
1308       would normally be passed onto the "string" or "tt" render-methods.
1309
1310       As with "render", you must call "process" once after building the form,
1311       and before calling "render_data".
1312
1313   render_data_non_recursive
1314       Like "render_data", but doesn't include the data for any child-
1315       elements.
1316

INTROSPECTION

1318   get_fields
1319       Arguments: [%options]
1320
1321       Arguments: [\%options]
1322
1323       Return Value: \@elements
1324
1325       Returns all fields in the form (specifically, all elements which have a
1326       true "is_field" in HTML::FormFu::Element value).
1327
1328       Accepts both "name" and "type" arguments to narrow the returned
1329       results.
1330
1331           $form->get_fields({
1332               name => 'foo',
1333               type => 'Radio',
1334           });
1335
1336       Accepts also an Regexp to search for results.
1337
1338           $form->get_elements({
1339               name => qr/oo/,
1340           });
1341
1342   get_field
1343       Arguments: [%options]
1344
1345       Arguments: [\%options]
1346
1347       Return Value: $element
1348
1349       Accepts the same arguments as "get_fields", but only returns the first
1350       field found.
1351
1352   get_elements
1353       Arguments: [%options]
1354
1355       Arguments: [\%options]
1356
1357       Return Value: \@elements
1358
1359       Returns all top-level elements in the form (not recursive).  See
1360       "get_all_elements" for a recursive version.
1361
1362       Accepts both "name" and "type" arguments to narrow the returned
1363       results.
1364
1365           $form->get_elements({
1366               name => 'foo',
1367               type => 'Radio',
1368           });
1369
1370       Accepts also an Regexp to search for results.
1371
1372           $form->get_elements({
1373               name => qr/oo/,
1374           });
1375
1376   get_element
1377       Arguments: [%options]
1378
1379       Arguments: [\%options]
1380
1381       Return Value: $element
1382
1383       Accepts the same arguments as "get_elements", but only returns the
1384       first element found.
1385
1386       See "get_all_element" for a recursive version.
1387
1388   get_all_elements
1389       Arguments: [%options]
1390
1391       Arguments: [\%options]
1392
1393       Return Value: \@elements
1394
1395       Returns all elements in the form recursively.
1396
1397       Optionally accepts both "name" and "type" arguments to narrow the
1398       returned results.
1399
1400           # return all Text elements
1401
1402           $form->get_all_elements({
1403               type => 'Text',
1404           });
1405
1406       Accepts also an Regexp to search for results.
1407
1408           $form->get_elements({
1409               name => qr/oo/,
1410           });
1411
1412       See "get_elements" for a non-recursive version.
1413
1414   get_all_element
1415       Arguments: [%options]
1416
1417       Arguments: [\%options]
1418
1419       Return Value: $element
1420
1421       Accepts the same arguments as "get_all_elements", but only returns the
1422       first element found.
1423
1424           # return the first Text field found, regardless of whether it's
1425           # within a fieldset or not
1426
1427           $form->get_all_element({
1428               type => 'Text',
1429           });
1430
1431       Accepts also an Regexp to search for results.
1432
1433           $form->get_elements({
1434               name => qr/oo/,
1435           });
1436
1437       See "get_all_elements" for a non-recursive version.
1438
1439   get_deflators
1440       Arguments: [%options]
1441
1442       Arguments: [\%options]
1443
1444       Return Value: \@deflators
1445
1446       Returns all top-level deflators from all fields.
1447
1448       Accepts both "name" and "type" arguments to narrow the returned
1449       results.
1450
1451           $form->get_deflators({
1452               name => 'foo',
1453               type => 'Strftime',
1454           });
1455
1456   get_deflator
1457       Arguments: [%options]
1458
1459       Arguments: [\%options]
1460
1461       Return Value: $element
1462
1463       Accepts the same arguments as "get_deflators", but only returns the
1464       first deflator found.
1465
1466   get_filters
1467       Arguments: [%options]
1468
1469       Arguments: [\%options]
1470
1471       Return Value: \@filters
1472
1473       Returns all top-level filters from all fields.
1474
1475       Accepts both "name" and "type" arguments to narrow the returned
1476       results.
1477
1478           $form->get_filters({
1479               name => 'foo',
1480               type => 'LowerCase',
1481           });
1482
1483   get_filter
1484       Arguments: [%options]
1485
1486       Arguments: [\%options]
1487
1488       Return Value: $filter
1489
1490       Accepts the same arguments as "get_filters", but only returns the first
1491       filter found.
1492
1493   get_constraints
1494       Arguments: [%options]
1495
1496       Arguments: [\%options]
1497
1498       Return Value: \@constraints
1499
1500       Returns all constraints from all fields.
1501
1502       Accepts both "name" and "type" arguments to narrow the returned
1503       results.
1504
1505           $form->get_constraints({
1506               name => 'foo',
1507               type => 'Equal',
1508           });
1509
1510   get_constraint
1511       Arguments: [%options]
1512
1513       Arguments: [\%options]
1514
1515       Return Value: $constraint
1516
1517       Accepts the same arguments as "get_constraints", but only returns the
1518       first constraint found.
1519
1520   get_inflators
1521       Arguments: [%options]
1522
1523       Arguments: [\%options]
1524
1525       Return Value: \@inflators
1526
1527       Returns all inflators from all fields.
1528
1529       Accepts both "name" and "type" arguments to narrow the returned
1530       results.
1531
1532           $form->get_inflators({
1533               name => 'foo',
1534               type => 'DateTime',
1535           });
1536
1537   get_inflator
1538       Arguments: [%options]
1539
1540       Arguments: [\%options]
1541
1542       Return Value: $inflator
1543
1544       Accepts the same arguments as "get_inflators", but only returns the
1545       first inflator found.
1546
1547   get_validators
1548       Arguments: [%options]
1549
1550       Arguments: [\%options]
1551
1552       Return Value: \@validators
1553
1554       Returns all validators from all fields.
1555
1556       Accepts both "name" and "type" arguments to narrow the returned
1557       results.
1558
1559           $form->get_validators({
1560               name => 'foo',
1561               type => 'Callback',
1562           });
1563
1564   get_validator
1565       Arguments: [%options]
1566
1567       Arguments: [\%options]
1568
1569       Return Value: $validator
1570
1571       Accepts the same arguments as "get_validators", but only returns the
1572       first validator found.
1573
1574   get_transformers
1575       Arguments: [%options]
1576
1577       Arguments: [\%options]
1578
1579       Return Value: \@transformers
1580
1581       Returns all transformers from all fields.
1582
1583       Accepts both "name" and "type" arguments to narrow the returned
1584       results.
1585
1586           $form->get_transformers({
1587               name => 'foo',
1588               type => 'Callback',
1589           });
1590
1591   get_transformer
1592       Arguments: [%options]
1593
1594       Arguments: [\%options]
1595
1596       Return Value: $transformer
1597
1598       Accepts the same arguments as "get_transformers", but only returns the
1599       first transformer found.
1600
1601   clone
1602       Returns a deep clone of the <$form> object.
1603
1604       Because of scoping issues, code references (such as in Callback
1605       constraints) are copied instead of cloned.
1606

ATTRIBUTE ACCESSORS

1608       For the basic method, e.g. "/attributes":
1609
1610       Arguments: [%attributes]
1611
1612       Arguments: [\%attributes]
1613
1614       Return Value: $form
1615
1616       As a special case, if no arguments are passed, the attributes hash-ref
1617       is returned. This allows the following idioms.
1618
1619           # set a value
1620           $form->attributes->{id} = 'form';
1621
1622           # delete all attributes
1623           %{ $form->attributes } = ();
1624
1625       All methods documented as 'attribute accessors' also have the following
1626       variants generated:
1627
1628       *_xml can be used as a setter, and ensures that its argument is not
1629       XML-escaped in the rendered form.
1630
1631       *_loc can he used as a setter, and passes the arguments through
1632       "localize".
1633
1634       "add_*" can be used to append a word to an attribute without
1635       overwriting any already-existing value.
1636
1637           # Example
1638           $form->attributes({ class => 'fancy' });
1639           $form->add_attributes({ class => 'pants' });
1640           # class="fancy pants"
1641
1642       "add_*_xml", like "add_*", but ensures it doesn't get XML-escaped.
1643
1644       "add_*_loc", like "add_*", but passing the arguments through
1645       "localize".
1646
1647       "del_*" can be used to remove a word from an attribute value.
1648
1649           # Example
1650           $form->attributes({ class => 'fancy pants' });
1651           $form->del_attributes({ class => 'pants' });
1652           # class="fancy"
1653
1654       "del_*_xml", like "del_*", but ensures it doesn't get XML-escaped.
1655
1656       "del_*_loc", like "del_*", but passing the arguments through
1657       "localize".
1658
1659       Also, any attribute method-name which contains the word "attributes"
1660       also has aliases created for all these variants, with the word
1661       "attributes" replaced by "attrs".
1662
1663           # For example, the attributes() method would have all these variant
1664           # methods available
1665
1666           $form->attributes({ class => 'fancy' });
1667           $form->attributes_xml({ title => '<b>fancy</b>' });
1668           $form->attributes_loc({ title => 'fancy' });
1669           $form->add_attributes({ class => 'fancy' });
1670           $form->add_attributes_xml({ title => '<b>fancy</b>' });
1671           $form->add_attributes_loc({ title => 'fancy' });
1672           $form->del_attributes({ class => 'fancy' });
1673           $form->del_attributes_xml({ title => '<b>fancy</b>' });
1674           $form->del_attributes_loc({ title => 'fancy' });
1675
1676           # Because the method contains the word 'attributes', it also gets the
1677           # following short-forms
1678
1679           $form->attrs({ class => 'fancy' });
1680           $form->attrs_xml({ title => '<b>fancy</b>' });
1681           $form->attrs_loc({ title => 'fancy' });
1682           $form->add_attrs({ class => 'fancy' });
1683           $form->add_attrs_xml({ title => '<b>fancy</b>' });
1684           $form->add_attrs_loc({ title => 'fancy' });
1685           $form->del_attrs({ class => 'fancy' });
1686           $form->del_attrs_xml({ title => '<b>fancy</b>' });
1687           $form->del_attrs_loc({ title => 'fancy' });
1688

ATTRIBUTE SHORT-CUTS

1690       All methods documented as 'attribute short-cuts' are short-cuts to
1691       directly access individual attribute key/values.
1692
1693           # Example
1694           $form->id( 'login' );
1695           $id = $form->id;
1696
1697           # is equivalent to:
1698           $form->attributes({ id => 'login' });
1699           $id = $form->attributes->{id};
1700
1701       All attribute short-cuts also have a *_xml variant.
1702
1703           # Example
1704           $form->id_xml( $xml );
1705
1706           # is equivalent to:
1707           $form->attributes_xml({ id => $xml });
1708
1709       All attribute short-cuts also have a *_loc variant.
1710
1711           # Example
1712           $form->title_loc( $key );
1713
1714           # is equivalent to:
1715           $form->attributes_loc({ title => $key });
1716

INHERITING ACCESSORS

1718       All methods documented as 'inheriting accessors' can be set on the
1719       form, a block element or a single field element.  When the value is
1720       read, if no value is defined it automatically traverses the element's
1721       hierarchy of parents, searching for a defined value.
1722
1723       All inherited accessors also have a *_no_inherit variant, which can be
1724       used as a getter to fetch any defined value, without traversing the
1725       hierarchy of parents. This variant cannot be used as a setter.
1726
1727       E.g., the "auto_id" has a variant named "auto_id_no_inherit".
1728

OUTPUT ACCESSORS

1730       All methods documented as 'output accessors' also have *_xml and *_loc
1731       variants.
1732
1733       The *_xml variant can be used as a setter, and ensures that its
1734       argument is not XML-escaped in the rendered form.
1735
1736       The *_loc variant can be used as a setter, and passes the arguments
1737       through "localize".
1738
1739       E.g., the label method has variants named "label_xml" and "label_loc".
1740

BOOLEAN ATTRIBUTE ACCESSORS

1742       To support boolean attributes, whose value should either be equal to
1743       the attribute name, or empty. Any true value will switch the attribute
1744       'on', any false value will remove the attribute.
1745
1746           # Example
1747
1748           $field->autofocus(1);
1749           # equivalent to:
1750           $field->attributes({ autofocus => 'autofocus' });
1751
1752           $field->autofocus(0);;
1753           # equivalent to:
1754           delete $field->attributes->{autofocus};
1755

ATTRIBUTE SUBSTITUTIONS

1757       Some attributes support character substitutions: the following
1758       substitutions are possible:
1759
1760           %f # $form->id
1761           %n # $field->name
1762           %t # lc( $field->type )
1763           %r # $block->repeatable_count
1764           %s # $error->stage
1765
1766       These allow each field to have consistent attributes, while remaining
1767       unique.
1768

DEPRECATION POLICY

1770       We try our best to not make incompatible changes, but if they're
1771       required we'll make every effort possible to provide backwards
1772       compatibility for several release-cycles, issuing a warnings about the
1773       changes, before removing the legacy features.
1774

RESTORING LEGACY HTML CLASSES

1776       "v1.00" dropped most of the default HTML class-names, with the
1777       intention that each application should define just what it needs,
1778       without needing to reset unwanted options first. We also gain the
1779       benefit of less markup being generated, speeding up both render and
1780       HTTP transfers.
1781
1782       To restore the previous behaviour, set the following options.
1783
1784       If you're using best practices, you'll only need to set these once per-
1785       application in your app-wide config file.
1786
1787           ---
1788           auto_container_class: '%t'
1789           auto_container_label_class: 'label'
1790           auto_container_comment_class: 'comment'
1791           auto_comment_class: 'comment'
1792           auto_container_error_class: 'error'
1793           auto_container_per_error_class: 'error_%s_%t'
1794           auto_error_class: 'error_message error_%s_%t'
1795

DEPRECATED METHODS

1797       See "DEPRECATED METHODS" in HTML::FormFu::Role::Element::Field.
1798

REMOVED METHODS

1800       See also "REMOVED METHODS" in HTML::FormFu::Element.
1801
1802   element_defaults
1803       Has been removed; see "default_args" instead.
1804
1805   model_class
1806       Has been removed; use "default_model" instead.
1807
1808   defaults_from_model
1809       Has been removed; use "default_values" in HTML::FormFu::Model instead.
1810
1811   save_to_model
1812       Has been removed; use "update" in HTML::FormFu::Model instead.
1813

BEST PRACTICES

1815       It is advisable to keep application-wide (or global) settings in a
1816       single config file, which should be loaded by each form.
1817
1818       See "load_config_file".
1819

COOKBOOK

1821       HTML::FormFu::Manual::Cookbook
1822
1823   UNICODE
1824       HTML::FormFu::Manual::Unicode
1825

EXAMPLES

1827   vertically-aligned CSS
1828       The distribution directory "examples/vertically-aligned" contains a
1829       form with example CSS for a "vertically aligned" theme.
1830
1831       This can be viewed by opening the file "vertically-aligned.html" in a
1832       web-browser.
1833
1834       If you wish to experiment with making changes, the form is defined in
1835       file "vertically-aligned.yml", and the HTML file can be updated with
1836       any changes by running the following command (while in the distribution
1837       root directory).
1838
1839           perl examples/vertically-aligned/vertically-aligned.pl
1840
1841       This uses the Template Toolkit file "vertically-aligned.tt", and the
1842       CSS is defined in files "vertically-aligned.css" and
1843       "vertically-aligned-ie.css".
1844

SUPPORT

1846       Project Page:
1847
1848       <http://code.google.com/p/html-formfu/>
1849
1850       Mailing list:
1851
1852       <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/html-formfu>
1853
1854       Mailing list archives:
1855
1856       <http://lists.scsys.co.uk/pipermail/html-formfu/>
1857
1858       IRC:
1859
1860       "irc.perl.org", channel "#formfu"
1861
1862       The HTML::Widget archives
1863       <http://lists.scsys.co.uk/pipermail/html-widget/> between January and
1864       May 2007 also contain discussion regarding HTML::FormFu.
1865

BUGS

1867       Please submit bugs / feature requests to
1868       <https://github.com/FormFu/HTML-FormFu/issues> (preferred) or
1869       <http://rt.perl.org>.
1870

PATCHES

1872       To help patches be applied quickly, please send them to the mailing
1873       list; attached, rather than inline; against subversion, rather than a
1874       cpan version (run "svn diff > patchfile"); mention which svn version
1875       it's against.  Mailing list messages are limited to 256KB, so gzip the
1876       patch if necessary.
1877

GITHUB REPOSITORY

1879       This module's sourcecode is maintained in a git repository at
1880       <git://github.com/FormFu/HTML-FormFu.git>
1881
1882       The project page is <https://github.com/FormFu/HTML-FormFu>
1883

SEE ALSO

1885       HTML::FormFu::Imager
1886
1887       Catalyst::Controller::HTML::FormFu
1888
1889       HTML::FormFu::Model::DBIC
1890

CONTRIBUTORS

1892       Brian Cassidy
1893
1894       Ozum Eldogan
1895
1896       Ruben Fonseca
1897
1898       Ronald Kimball
1899
1900       Daisuke Maki
1901
1902       Andreas Marienborg
1903
1904       Mario Minati
1905
1906       Steve Nolte
1907
1908       Moritz Onken
1909
1910       Doug Orleans
1911
1912       Matthias Dietrich
1913
1914       Dean Hamstead
1915
1916       Karen Etheridge
1917
1918       Nigel Metheringham
1919
1920       Based on the original source code of HTML::Widget, by Sebastian Riedel,
1921       "sri@oook.de".
1922

AUTHOR

1924       Carl Franks <cpan@fireartist.com>
1925
1927       This software is copyright (c) 2018 by Carl Franks.
1928
1929       This is free software; you can redistribute it and/or modify it under
1930       the same terms as the Perl 5 programming language system itself.
1931
1932
1933
1934perl v5.34.0                      2021-07-22                   HTML::FormFu(3)
Impressum