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

BETA SOFTWARE

9       There may be API changes required before the 1.0 release. Any
10       incompatible changes will first be discussed on the mailing list.  See
11       "DEPRECATION POLICY" for further details.
12
13       Work is still needed on the documentation, if you come across any
14       errors or find something confusing, please give feedback via the
15       mailing list.
16

SYNOPSIS

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

DESCRIPTION

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

BUILDING A FORM

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

FORM LOGIC AND VALIDATION

614       HTML::FormFu provides several stages for what is traditionally
615       described as validation. These are:
616
617       HTML::FormFu::Filter
618       HTML::FormFu::Constraint
619       HTML::FormFu::Inflator
620       HTML::FormFu::Validator
621       HTML::FormFu::Transformer
622
623       The first stage, the filters, allow for cleanup of user-input, such as
624       encoding, or removing leading/trailing whitespace, or removing non-
625       digit characters from a creditcard number.
626
627       All of the following stages allow for more complex processing, and each
628       of them have a mechanism to allow exceptions to be thrown, to represent
629       input errors. In each stage, all form fields must be processed without
630       error for the next stage to proceed. If there were any errors, the form
631       should be re-displayed to the user, to allow them to input correct
632       values.
633
634       Constraints are intended for low-level validation of values, such as
635       "is this an integer?", "is this value within bounds?" or "is this a
636       valid email address?".
637
638       Inflators are intended to allow a value to be turned into an
639       appropriate object. The resulting object will be passed to subsequent
640       Validators and Transformers, and will also be returned by "params" and
641       "param".
642
643       Validators are intended for higher-level validation, such as business-
644       logic and database constraints such as "is this username unique?".
645       Validators are only run if all Constraints and Inflators have run
646       without errors. It is expected that most Validators will be
647       application-specific, and so each will be implemented as a separate
648       class written by the HTML::FormFu user.
649
650   filters
651   filter
652       Arguments: $type
653
654       Arguments: \%options
655
656       Return Value: $filter
657
658       Arguments: \@arrayref_of_types_or_options
659
660       Return Value: @filters
661
662       If you provide a "name" or "names" value, the filter will be added to
663       just that named field.  If you do not provide a "name" or "names"
664       value, the filter will be added to all fields already attached to the
665       form.
666
667       See "CORE FILTERS" in HTML::FormFu::Filter for a list of core filters.
668
669       If you want to load a filter in a namespace other than
670       "HTML::FormFu::Filter::", you can use a fully qualified package-name by
671       prefixing it with "+".
672
673       "filter" is an alias for "filters".
674
675   constraints
676   constraint
677       Arguments: $type
678
679       Arguments: \%options
680
681       Return Value: $constraint
682
683       Arguments: \@arrayref_of_types_or_options
684
685       Return Value: @constraints
686
687       See "CORE CONSTRAINTS" in HTML::FormFu::Constraint for a list of core
688       constraints.
689
690       If a "name" attribute isn't provided, a new constraint is created for
691       and added to every field on the form.
692
693       If you want to load a constraint in a namespace other than
694       "HTML::FormFu::Constraint::", you can use a fully qualified package-
695       name by prefixing it with "+".
696
697       "constraint" is an alias for "constraints".
698
699   inflators
700   inflator
701       Arguments: $type
702
703       Arguments: \%options
704
705       Return Value: $inflator
706
707       Arguments: \@arrayref_of_types_or_options
708
709       Return Value: @inflators
710
711       See "CORE INFLATORS" in HTML::FormFu::Inflator for a list of core
712       inflators.
713
714       If a "name" attribute isn't provided, a new inflator is created for and
715       added to every field on the form.
716
717       If you want to load an inflator in a namespace other than
718       "HTML::FormFu::Inflator::", you can use a fully qualified package-name
719       by prefixing it with "+".
720
721       "inflator" is an alias for "inflators".
722
723   validators
724   validator
725       Arguments: $type
726
727       Arguments: \%options
728
729       Return Value: $validator
730
731       Arguments: \@arrayref_of_types_or_options
732
733       Return Value: @validators
734
735       See "CORE VALIDATORS" in HTML::FormFu::Validator for a list of core
736       validators.
737
738       If a "name" attribute isn't provided, a new validator is created for
739       and added to every field on the form.
740
741       If you want to load a validator in a namespace other than
742       "HTML::FormFu::Validator::", you can use a fully qualified package-name
743       by prefixing it with "+".
744
745       "validator" is an alias for "validators".
746
747   transformers
748   transformer
749       Arguments: $type
750
751       Arguments: \%options
752
753       Return Value: $transformer
754
755       Arguments: \@arrayref_of_types_or_options
756
757       Return Value: @transformers
758
759       See "CORE TRANSFORMERS" in HTML::FormFu::Transformer for a list of core
760       transformers.
761
762       If a "name" attribute isn't provided, a new transformer is created for
763       and added to every field on the form.
764
765       If you want to load a transformer in a namespace other than
766       "HTML::FormFu::Transformer::", you can use a fully qualified package-
767       name by prefixing it with "+".
768
769       "transformer" is an alias for "transformers".
770

CHANGING DEFAULT BEHAVIOUR

772   render_processed_value
773       The default behaviour when re-displaying a form after a submission, is
774       that the field contains the original unchanged user-submitted value.
775
776       If "render_processed_value" is true, the field value will be the final
777       result after all Filters, Inflators and Transformers have been run.
778       Deflators will also be run on the value.
779
780       If you set this on a field with an Inflator, but without an equivalent
781       Deflator, you should ensure that the Inflators stringify back to a
782       usable value, so as not to confuse / annoy the user.
783
784       Default Value: false
785
786       This method is a special 'inherited accessor', which means it can be
787       set on the form, a block element or a single element. When the value is
788       read, if no value is defined it automatically traverses the element's
789       hierarchy of parents, through any block elements and up to the form,
790       searching for a defined value.
791
792   force_errors
793       Force a constraint to fail, regardless of user input.
794
795       If this is called at runtime, after the form has already been
796       processed, you must called "process" in HTML::FormFu again before
797       redisplaying the form to the user.
798
799       Default Value: false
800
801       This method is a special 'inherited accessor', which means it can be
802       set on the form, a block element, an element or a single constraint.
803       When the value is read, if no value is defined it automatically
804       traverses the element's hierarchy of parents, through any block
805       elements and up to the form, searching for a defined value.
806
807   params_ignore_underscore
808       If true, causes "params", "param" and "valid" to ignore any fields
809       whose name starts with an underscore "_".
810
811       The field is still processed as normal, and errors will cause
812       "submitted_and_valid" to return false.
813
814       Default Value: false
815

FORM ATTRIBUTES

817       All attributes are added to the rendered form's start tag.
818
819   attributes
820   attrs
821       Arguments: [%attributes]
822
823       Arguments: [\%attributes]
824
825       Return Value: $form
826
827       Accepts either a list of key/value pairs, or a hash-ref.
828
829           ---
830           attributes:
831             id: form
832             class: fancy_form
833
834       As a special case, if no arguments are passed, the attributes hash-ref
835       is returned. This allows the following idioms.
836
837           # set a value
838           $form->attributes->{id} = 'form';
839
840           # delete all attributes
841           %{ $form->attributes } = ();
842
843       "attrs" is an alias for "attributes".
844
845   attributes_xml
846   attrs_xml
847       Provides the same functionality as "attributes", but values won't be
848       XML-escaped.
849
850       "attrs_xml" is an alias for "attributes_xml".
851
852   add_attributes
853   add_attrs
854       Arguments: [%attributes]
855
856       Arguments: [\%attributes]
857
858       Return Value: $form
859
860       Accepts either a list of key/value pairs, or a hash-ref.
861
862           $form->add_attributes( $key => $value );
863           $form->add_attributes( { $key => $value } );
864
865       All values are appended to existing values, with a preceding space
866       character. This is primarily to allow the easy addition of new names to
867       the class attribute.
868
869           $form->attributes({ class => 'foo' });
870
871           $form->add_attributes({ class => 'bar' });
872
873           # class is now 'foo bar'
874
875       "add_attrs" is an alias for "add_attributes".
876
877   add_attributes_xml
878   add_attrs_xml
879       Provides the same functionality as "add_attributes", but values won't
880       be XML-escaped.
881
882       "add_attrs_xml" is an alias for "add_attributes_xml".
883
884   del_attributes
885   del_attrs
886       Arguments: [%attributes]
887
888       Arguments: [\%attributes]
889
890       Return Value: $form
891
892       Accepts either a list of key/value pairs, or a hash-ref.
893
894           $form->del_attributes( $key => $value );
895           $form->del_attributes( { $key => $value } );
896
897       All values are removed from the attribute value.
898
899           $form->attributes({ class => 'foo bar' });
900
901           $form->del_attributes({ class => 'bar' });
902
903           # class is now 'foo'
904
905       "del_attrs" is an alias for "del_attributes".
906
907   del_attributes_xml
908   del_attrs_xml
909       Provides the same functionality as "del_attributes", but values won't
910       be XML-escaped.
911
912       "del_attrs_xml" is an alias for "del_attributes_xml".
913
914       The following methods are shortcuts for accessing "attributes" keys.
915
916   id
917       Arguments: [$id]
918
919       Return Value: $id
920
921       Get or set the form's DOM id.
922
923       Default Value: none
924
925   action
926       Arguments: [$uri]
927
928       Return Value: $uri
929
930       Get or set the action associated with the form. The default is no
931       action, which causes most browsers to submit to the current URI.
932
933       Default Value: ""
934
935   enctype
936       Arguments: [$enctype]
937
938       Return Value: $enctype
939
940       Get or set the encoding type of the form. Valid values are
941       "application/x-www-form-urlencoded" and "multipart/form-data".
942
943       If the form contains a File element, the enctype is automatically set
944       to "multipart/form-data".
945
946   method
947       Arguments: [$method]
948
949       Return Value: $method
950
951       Get or set the method used to submit the form. Can be set to either
952       "post" or "get".
953
954       Default Value: "post"
955

CSS CLASSES

957   auto_id
958       Arguments: [$string]
959
960       If set, then each form field will be given an auto-generated id
961       attribute, if it doesn't have one already.
962
963       The following character substitution will be performed: %f will be
964       replaced by $form->id, %n will be replaced by $field->name, %r will be
965       replaced by $block->repeatable_count.
966
967       Default Value: not defined
968
969       This method is a special 'inherited accessor', which means it can be
970       set on the form, a block element or a single element. When the value is
971       read, if no value is defined it automatically traverses the element's
972       hierarchy of parents, through any block elements and up to the form,
973       searching for a defined value.
974
975   auto_label
976       Arguments: [$string]
977
978       If set, then each form field will be given an auto-generated label, if
979       it doesn't have one already.
980
981       The following character substitution will be performed: %f will be
982       replaced by $form->id, %n will be replaced by $field->name.
983
984       The generated string will be passed to "localize" to create the label.
985
986       Default Value: not defined
987
988       This method is a special 'inherited accessor', which means it can be
989       set on the form, a block element or a single element. When the value is
990       read, if no value is defined it automatically traverses the element's
991       hierarchy of parents, through any block elements and up to the form,
992       searching for a defined value.
993
994   auto_error_class
995       Arguments: [$string]
996
997       If set, then each form error will be given an auto-generated class-
998       name.
999
1000       The following character substitution will be performed: %f will be
1001       replaced by $form->id, %n will be replaced by $field->name, %t will be
1002       replaced by lc( $field->type ), %s will be replaced by $error->stage.
1003
1004       Default Value: 'error_%s_%t'
1005
1006       This method is a special 'inherited accessor', which means it can be
1007       set on the form, a block element or a single element. When the value is
1008       read, if no value is defined it automatically traverses the element's
1009       hierarchy of parents, through any block elements and up to the form,
1010       searching for a defined value.
1011
1012   auto_error_message
1013       Arguments: [$string]
1014
1015       If set, then each form field will be given an auto-generated message,
1016       if it doesn't have one already.
1017
1018       The following character substitution will be performed: %f will be
1019       replaced by $form->id, %n will be replaced by $field->name, %t will be
1020       replaced by lc( $field->type ), %s will be replaced by $error->stage.
1021
1022       The generated string will be passed to "localize" to create the
1023       message.
1024
1025       For example, a Required constraint will return the string
1026       "form_constraint_required". Under the default localization behaviour,
1027       the appropriate message for "form_constraint_required" will be used
1028       from the default I18N package.
1029
1030       Default Value: 'form_%s_%t'
1031
1032       This method is a special 'inherited accessor', which means it can be
1033       set on the form, a block element or a single element. When the value is
1034       read, if no value is defined it automatically traverses the element's
1035       hierarchy of parents, through any block elements and up to the form,
1036       searching for a defined value.
1037
1038   auto_constraint_class
1039       Arguments: [$string]
1040
1041       If set, then each form field will be given an auto-generated class-name
1042       for each associated constraint.
1043
1044       The following character substitution will be performed: %f will be
1045       replaced by $form->id, %n will be replaced by $field->name, %t will be
1046       replaced by lc( $field->type ).
1047
1048       Default Value: not defined
1049
1050       This method is a special 'inherited accessor', which means it can be
1051       set on the form, a block element or a single element. When the value is
1052       read, if no value is defined it automatically traverses the element's
1053       hierarchy of parents, through any block elements and up to the form,
1054       searching for a defined value.
1055
1056   auto_inflator_class
1057       Arguments: [$string]
1058
1059       If set, then each form field will be given an auto-generated class-name
1060       for each associated inflator.
1061
1062       The following character substitution will be performed: %f will be
1063       replaced by $form->id, %n will be replaced by $field->name, %t will be
1064       replaced by lc( $field->type ).
1065
1066       Default Value: not defined
1067
1068       This method is a special 'inherited accessor', which means it can be
1069       set on the form, a block element or a single element. When the value is
1070       read, if no value is defined it automatically traverses the element's
1071       hierarchy of parents, through any block elements and up to the form,
1072       searching for a defined value.
1073
1074   auto_validator_class
1075       Arguments: [$string]
1076
1077       If set, then each form field will be given an auto-generated class-name
1078       for each associated validator.
1079
1080       The following character substitution will be performed: %f will be
1081       replaced by $form->id, %n will be replaced by $field->name, %t will be
1082       replaced by lc( $field->type ).
1083
1084       Default Value: not defined
1085
1086       This method is a special 'inherited accessor', which means it can be
1087       set on the form, a block element or a single element. When the value is
1088       read, if no value is defined it automatically traverses the element's
1089       hierarchy of parents, through any block elements and up to the form,
1090       searching for a defined value.
1091
1092   auto_transformer_class
1093       Arguments: [$string]
1094
1095       If set, then each form field will be given an auto-generated class-name
1096       for each associated validator.
1097
1098       The following character substitution will be performed: %f will be
1099       replaced by $form->id, %n will be replaced by $field->name, %t will be
1100       replaced by lc( $field->type ).
1101
1102       Default Value: not defined
1103
1104       This method is a special 'inherited accessor', which means it can be
1105       set on the form, a block element or a single element. When the value is
1106       read, if no value is defined it automatically traverses the element's
1107       hierarchy of parents, through any block elements and up to the form,
1108       searching for a defined value.
1109

LOCALIZATION

1111   languages
1112       Arguments: [\@languages]
1113
1114       A list of languages which will be passed to the localization object.
1115
1116       Default Value: ['en']
1117
1118   localize_class
1119       Arguments: [$class_name]
1120
1121       Classname to be used for the default localization object.
1122
1123       Default Value: 'HTML::FormFu::I18N'
1124
1125   localize
1126   loc
1127       Arguments: [$key, @arguments]
1128
1129       Compatible with the "maketext" method in Locale::Maketext.
1130
1131   locale
1132       Arguments: $locale
1133
1134       Currently only used by HTML::FormFu::Deflator::FormatNumber and
1135       HTML::FormFu::Filter::FormatNumber.
1136
1137       This method is a special 'inherited accessor', which means it can be
1138       set on the form, a block element or a single element. When the value is
1139       read, if no value is defined it automatically traverses the element's
1140       hierarchy of parents, through any block elements and up to the form,
1141       searching for a defined value.
1142

PROCESSING A FORM

1144   query
1145       Arguments: [$query_object]
1146
1147       Arguments: \%params
1148
1149       Provide a CGI compatible query object or a hash-ref of submitted
1150       names/values. Alternatively, the query object can be passed directly to
1151       the "process" object.
1152
1153   query_type
1154       Arguments: [$query_type]
1155
1156       Set which module is being used to provide the "query".
1157
1158       The Catalyst::Controller::HTML::FormFu automatically sets this to
1159       "Catalyst".
1160
1161       Valid values are "CGI", "Catalyst" and "CGI::Simple".
1162
1163       Default Value: 'CGI'
1164
1165   process
1166       Arguments: [$query_object]
1167
1168       Arguments: [\%params]
1169
1170       Process the provided query object or input values. "process" must be
1171       called before calling any of the methods listed under "SUBMITTED FORM
1172       VALUES AND ERRORS" and "MODIFYING A SUBMITTED FORM".
1173
1174       "process" must also be called at least once before printing the form or
1175       calling "render" or "render_data".
1176
1177       Note to users of Catalyst::Controller::HTML::FormFu: Because "process"
1178       is automatically called for you by the Catalyst controller; if you make
1179       any modifications to the form within your action method, such as adding
1180       or changing elements, adding constraints, etc; you must call "process"
1181       again yourself before using "submitted_and_valid", any of the methods
1182       listed under "SUBMITTED FORM VALUES AND ERRORS" or "MODIFYING A
1183       SUBMITTED FORM", or rendering the form.
1184

SUBMITTED FORM VALUES AND ERRORS

1186   submitted
1187       Returns true if the form has been submitted. See "indicator" for
1188       details on how this is computed.
1189
1190   submitted_and_valid
1191       Shorthand for "$form->submitted && !$form->has_errors"
1192
1193   params
1194       Return Value: \%params
1195
1196       Returns a hash-ref of all valid input for which there were no errors.
1197
1198   param_value
1199       Arguments: $field_name
1200
1201       A more reliable, recommended version of "param". Guaranteed to always
1202       return a single value, regardless of whether it's called in list
1203       context or not. If multiple values were submitted, this only returns
1204       the first value. If the value is invalid or the form was not submitted,
1205       it returns "undef". This makes it suitable for use in list context,
1206       where a single value is required.
1207
1208           $db->update({
1209               name    => $form->param_value('name'),
1210               address => $form->param_value('address),
1211           });
1212
1213   param_array
1214       Arguments: $field_name
1215
1216       Guaranteed to always return an array-ref of values, regardless of
1217       context and regardless of whether multiple values were submitted or
1218       not. If the value is invalid or the form was not submitted, it returns
1219       an empty array-ref.
1220
1221   param_list
1222       Arguments: $field_name
1223
1224       Guaranteed to always return a list of values, regardless of context. If
1225       the value is invalid or the form was not submitted, it returns an empty
1226       list.
1227
1228   param
1229       Arguments: [$field_name]
1230
1231       Return Value: $input_value
1232
1233       Return Value: @valid_names
1234
1235       No longer recommended for use, as its behaviour is hard to predict. Use
1236       "param_value", "param_array" or "param_list" instead.
1237
1238       A (readonly) method similar to that of CGI's.
1239
1240       If a field name is given, in list-context returns any valid values
1241       submitted for that field, and in scalar-context returns only the first
1242       of any valid values submitted for that field.
1243
1244       If no argument is given, returns a list of all valid input field names
1245       without errors.
1246
1247       Passing more than 1 argument is a fatal error.
1248
1249   valid
1250       Arguments: [$field_name]
1251
1252       Return Value: @valid_names
1253
1254       Return Value: $bool
1255
1256       If a field name if given, returns "true" if that field had no errors
1257       and "false" if there were errors.
1258
1259       If no argument is given, returns a list of all valid input field names
1260       without errors.
1261
1262   has_errors
1263       Arguments: [$field_name]
1264
1265       Return Value: @names
1266
1267       Return Value: $bool
1268
1269       If a field name if given, returns "true" if that field had errors and
1270       "false" if there were no errors.
1271
1272       If no argument is given, returns a list of all input field names with
1273       errors.
1274
1275   get_errors
1276       Arguments: [%options]
1277
1278       Arguments: [\%options]
1279
1280       Return Value: \@errors
1281
1282       Returns an array-ref of exception objects from all fields in the form.
1283
1284       Accepts both "name", "type" and "stage" arguments to narrow the
1285       returned results.
1286
1287           $form->get_errors({
1288               name  => 'foo',
1289               type  => 'Regex',
1290               stage => 'constraint'
1291           });
1292
1293   get_error
1294       Arguments: [%options]
1295
1296       Arguments: [\%options]
1297
1298       Return Value: $error
1299
1300       Accepts the same arguments as "get_errors", but only returns the first
1301       error found.
1302

MODEL / DATABASE INTERACTION

1304       See HTML::FormFu::Model for further details and available models.
1305
1306   default_model
1307       Arguments: $model_name
1308
1309       Default Value: 'DBIC'
1310
1311   model
1312       Arguments: [$model_name]
1313
1314       Return Value: $model
1315
1316   model_config
1317       Arguments: \%config
1318

MODIFYING A SUBMITTED FORM

1320   add_valid
1321       Arguments: $name, $value
1322
1323       Return Value: $value
1324
1325       The provided value replaces any current value for the named field. This
1326       value will be returned in subsequent calls to "params" and "param" and
1327       the named field will be included in calculations for "valid".
1328
1329   clear_errors
1330       Deletes all errors from a submitted form.
1331

RENDERING A FORM

1333   render
1334       Return Value: $string
1335
1336       You must call "process" once after building the form, and before
1337       calling "render".
1338
1339   start
1340       Return Value: $string
1341
1342       Returns the form start tag, and any output of "form_error_message" and
1343       "javascript".
1344
1345       Implicitly uses the "tt" "render_method".
1346
1347   end
1348       Return Value: $string
1349
1350       Returns the form end tag.
1351
1352       Implicitly uses the "tt" "render_method".
1353
1354   hidden_fields
1355       Return Value: $string
1356
1357       Returns all hidden form fields.
1358

PLUGIN SYSTEM

1360       "HTML::FormFu" provides a plugin-system that allows plugins to be
1361       easily added to a form or element, to change the default behaviour or
1362       output.
1363
1364       See HTML::FormFu::Plugin for details.
1365

ADVANCED CUSTOMISATION

1367       By default, formfu renders "XHTML 1.0 Strict" compliant markup, with as
1368       little extra markup as possible, but with sufficient CSS class names to
1369       allow for a wide-range of output styles to be generated by changing
1370       only the CSS.
1371
1372       If you wish to customise the markup, you'll need to tell HTML::FormFu
1373       to use an external rendering engine, such as Template Toolkit or
1374       Template::Alloy. See "render_method" and "tt_module" for details.
1375
1376       Even if you set HTML::FormFu to use Template::Toolkit to render, the
1377       forms, HTML::FormFu can still be used in conjunction with whichever
1378       other templating system you prefer to use for your own page layouts,
1379       whether it's HTML::Template: "<TMPL_VAR form>", Petal: "<form
1380       tal:replace="form"></form>" or Template::Magic: "<!-- {form} -->".
1381
1382   render_method
1383       Default Value: "string"
1384
1385       Can be set to "tt" to generate the form with external template files.
1386
1387       To customise the markup, you'll need a copy of the template files,
1388       local to your application. See "Installing the TT templates" in
1389       HTML::FormFu::Manual::Cookbook for further details.
1390
1391       You can customise the markup for a single element by setting that
1392       element's "render_method" to "tt", while the rest of the form uses the
1393       default "string" render-method. Note though, that if you try setting
1394       the form or a Block's "render_method" to "tt", and then set a child
1395       element's "render_method" to "string", that setting will be ignored,
1396       and the child elements will still use the "tt" render-method.
1397
1398           ---
1399           elements:
1400             - name: foo
1401               render_method: tt
1402               filename: custom_field
1403
1404             - name: bar
1405
1406           # in this example, 'foo' will use a custom template,
1407           # while bar will use the default 'string' rendering method
1408
1409       This method is a special 'inherited accessor', which means it can be
1410       set on the form, a block element or a single element. When the value is
1411       read, if no value is defined it automatically traverses the element's
1412       hierarchy of parents, through any block elements and up to the form,
1413       searching for a defined value.
1414
1415   filename
1416       Change the template filename used for the form.
1417
1418       Default Value: "form"
1419
1420   tt_args
1421       Arguments: [\%constructor_arguments]
1422
1423       Accepts a hash-ref of arguments passed to "render_method", which is
1424       called internally by "render".
1425
1426       Within tt_args, the keys "RELATIVE" and "RECURSION" are overridden to
1427       always be true, as these are a basic requirement for the Template
1428       engine.
1429
1430       The system directory containing HTML::FormFu's template files is always
1431       added to the end of "INCLUDE_PATH", so that the core template files
1432       will be found. You only need to set this yourself if you have your own
1433       copy of the template files for customisation purposes.
1434
1435       This method is a special 'inherited accessor', which means it can be
1436       set on the form, a block element or a single element. When the value is
1437       read, if no value is defined it automatically traverses the element's
1438       hierarchy of parents, through any block elements and up to the form,
1439       searching for a defined value.
1440
1441   add_tt_args
1442       Arguments: [\%constructor_arguments]
1443
1444       Ensures that the hash-ref argument is merged with any existing hash-ref
1445       value of "tt_args".
1446
1447   tt_module
1448       Default Value: Template
1449
1450       The module used when "render_method" is set to "tt". Should provide an
1451       interface compatible with Template.
1452
1453       This method is a special 'inherited accessor', which means it can be
1454       set on the form, a block element or a single element. When the value is
1455       read, if no value is defined it automatically traverses the element's
1456       hierarchy of parents, through any block elements and up to the form,
1457       searching for a defined value.
1458
1459   render_data
1460       Usually called implicitly by "render". Returns the data structure that
1461       would normally be passed onto the "string" or "tt" render-methods.
1462
1463       As with "render", you must call "process" once after building the form,
1464       and before calling "render_data".
1465
1466   render_data_non_recursive
1467       Like "render_data", but doesn't include the data for any child-
1468       elements.
1469

INTROSPECTION

1471   get_fields
1472       Arguments: [%options]
1473
1474       Arguments: [\%options]
1475
1476       Return Value: \@elements
1477
1478       Returns all fields in the form (specifically, all elements which have a
1479       true "is_field" in HTML::FormFu::Element value).
1480
1481       Accepts both "name" and "type" arguments to narrow the returned
1482       results.
1483
1484           $form->get_fields({
1485               name => 'foo',
1486               type => 'Radio',
1487           });
1488
1489       Accepts also an Regexp to search for results.
1490
1491           $form->get_elements({
1492               name => qr/oo/,
1493           });
1494
1495   get_field
1496       Arguments: [%options]
1497
1498       Arguments: [\%options]
1499
1500       Return Value: $element
1501
1502       Accepts the same arguments as "get_fields", but only returns the first
1503       field found.
1504
1505   get_elements
1506       Arguments: [%options]
1507
1508       Arguments: [\%options]
1509
1510       Return Value: \@elements
1511
1512       Returns all top-level elements in the form (not recursive).  See
1513       "get_all_elements" for a recursive version.
1514
1515       Accepts both "name" and "type" arguments to narrow the returned
1516       results.
1517
1518           $form->get_elements({
1519               name => 'foo',
1520               type => 'Radio',
1521           });
1522
1523       Accepts also an Regexp to search for results.
1524
1525           $form->get_elements({
1526               name => qr/oo/,
1527           });
1528
1529   get_element
1530       Arguments: [%options]
1531
1532       Arguments: [\%options]
1533
1534       Return Value: $element
1535
1536       Accepts the same arguments as "get_elements", but only returns the
1537       first element found.
1538
1539       See "get_all_element" for a recursive version.
1540
1541   get_all_elements
1542       Arguments: [%options]
1543
1544       Arguments: [\%options]
1545
1546       Return Value: \@elements
1547
1548       Returns all elements in the form recursively.
1549
1550       Optionally accepts both "name" and "type" arguments to narrow the
1551       returned results.
1552
1553           # return all Text elements
1554
1555           $form->get_all_elements({
1556               type => 'Text',
1557           });
1558
1559       Accepts also an Regexp to search for results.
1560
1561           $form->get_elements({
1562               name => qr/oo/,
1563           });
1564
1565       See "get_elements" for a non-recursive version.
1566
1567   get_all_element
1568       Arguments: [%options]
1569
1570       Arguments: [\%options]
1571
1572       Return Value: $element
1573
1574       Accepts the same arguments as "get_all_elements", but only returns the
1575       first element found.
1576
1577           # return the first Text field found, regardless of whether it's
1578           # within a fieldset or not
1579
1580           $form->get_all_element({
1581               type => 'Text',
1582           });
1583
1584       Accepts also an Regexp to search for results.
1585
1586           $form->get_elements({
1587               name => qr/oo/,
1588           });
1589
1590       See "get_all_elements" for a non-recursive version.
1591
1592   get_deflators
1593       Arguments: [%options]
1594
1595       Arguments: [\%options]
1596
1597       Return Value: \@deflators
1598
1599       Returns all top-level deflators from all fields.
1600
1601       Accepts both "name" and "type" arguments to narrow the returned
1602       results.
1603
1604           $form->get_deflators({
1605               name => 'foo',
1606               type => 'Strftime',
1607           });
1608
1609   get_deflator
1610       Arguments: [%options]
1611
1612       Arguments: [\%options]
1613
1614       Return Value: $element
1615
1616       Accepts the same arguments as "get_deflators", but only returns the
1617       first deflator found.
1618
1619   get_filters
1620       Arguments: [%options]
1621
1622       Arguments: [\%options]
1623
1624       Return Value: \@filters
1625
1626       Returns all top-level filters from all fields.
1627
1628       Accepts both "name" and "type" arguments to narrow the returned
1629       results.
1630
1631           $form->get_filters({
1632               name => 'foo',
1633               type => 'LowerCase',
1634           });
1635
1636   get_filter
1637       Arguments: [%options]
1638
1639       Arguments: [\%options]
1640
1641       Return Value: $filter
1642
1643       Accepts the same arguments as "get_filters", but only returns the first
1644       filter found.
1645
1646   get_constraints
1647       Arguments: [%options]
1648
1649       Arguments: [\%options]
1650
1651       Return Value: \@constraints
1652
1653       Returns all constraints from all fields.
1654
1655       Accepts both "name" and "type" arguments to narrow the returned
1656       results.
1657
1658           $form->get_constraints({
1659               name => 'foo',
1660               type => 'Equal',
1661           });
1662
1663   get_constraint
1664       Arguments: [%options]
1665
1666       Arguments: [\%options]
1667
1668       Return Value: $constraint
1669
1670       Accepts the same arguments as "get_constraints", but only returns the
1671       first constraint found.
1672
1673   get_inflators
1674       Arguments: [%options]
1675
1676       Arguments: [\%options]
1677
1678       Return Value: \@inflators
1679
1680       Returns all inflators from all fields.
1681
1682       Accepts both "name" and "type" arguments to narrow the returned
1683       results.
1684
1685           $form->get_inflators({
1686               name => 'foo',
1687               type => 'DateTime',
1688           });
1689
1690   get_inflator
1691       Arguments: [%options]
1692
1693       Arguments: [\%options]
1694
1695       Return Value: $inflator
1696
1697       Accepts the same arguments as "get_inflators", but only returns the
1698       first inflator found.
1699
1700   get_validators
1701       Arguments: [%options]
1702
1703       Arguments: [\%options]
1704
1705       Return Value: \@validators
1706
1707       Returns all validators from all fields.
1708
1709       Accepts both "name" and "type" arguments to narrow the returned
1710       results.
1711
1712           $form->get_validators({
1713               name => 'foo',
1714               type => 'Callback',
1715           });
1716
1717   get_validator
1718       Arguments: [%options]
1719
1720       Arguments: [\%options]
1721
1722       Return Value: $validator
1723
1724       Accepts the same arguments as "get_validators", but only returns the
1725       first validator found.
1726
1727   get_transformers
1728       Arguments: [%options]
1729
1730       Arguments: [\%options]
1731
1732       Return Value: \@transformers
1733
1734       Returns all transformers from all fields.
1735
1736       Accepts both "name" and "type" arguments to narrow the returned
1737       results.
1738
1739           $form->get_transformers({
1740               name => 'foo',
1741               type => 'Callback',
1742           });
1743
1744   get_transformer
1745       Arguments: [%options]
1746
1747       Arguments: [\%options]
1748
1749       Return Value: $transformer
1750
1751       Accepts the same arguments as "get_transformers", but only returns the
1752       first transformer found.
1753
1754   clone
1755       Returns a deep clone of the <$form> object.
1756
1757       Because of scoping issues, code references (such as in Callback
1758       constraints) are copied instead of cloned.
1759

DEPRECATED METHODS

1761   element_defaults
1762       Is deprecated and provided only for backwards compatibility. Will be
1763       removed at some point in the future.
1764
1765       See "default_args" instead.
1766
1767   model_class
1768       Is deprecated and provided only for backwards compatibility. Will be
1769       removed at some point in the future.
1770
1771       Use "default_model" instead.
1772
1773   defaults_from_model
1774       Is deprecated and provided only for backwards compatibility. Will be
1775       removed at some point in the future.
1776
1777       Use "default_values" in HTML::FormFu::Model instead.
1778
1779           $form->model->default_values( $object, \%config )
1780
1781   save_to_model
1782       Is deprecated and provided only for backwards compatibility. Will be
1783       removed at some point in the future.
1784
1785       Use "update" in HTML::FormFu::Model instead.
1786
1787           $form->model->update( $object, \%config )
1788

DEPRECATION POLICY

1790       We try our best to not make incompatible changes, but if they're
1791       required we'll make every effort possible to provide backwards
1792       compatibility for several release-cycles, issuing a warnings about the
1793       changes, before removing the legacy features.
1794

BEST PRACTICES

1796       It is advisable to keep application-wide (or global) settings in a
1797       single config file, which should be loaded by each form.
1798
1799       See "load_config_file".
1800

COOKBOOK

1802       HTML::FormFu::Manual::Cookbook
1803
1804   UNICODE
1805       HTML::FormFu::Manual::Unicode
1806

EXAMPLES

1808   vertically-aligned CSS
1809       The distribution directory "examples/vertically-aligned" contains a
1810       form with example CSS for a "vertically aligned" theme.
1811
1812       This can be viewed by opening the file "vertically-aligned.html" in a
1813       web-browser.
1814
1815       If you wish to experiment with making changes, the form is defined in
1816       file "vertically-aligned.yml", and the HTML file can be updated with
1817       any changes by running the following command (while in the distribution
1818       root directory).
1819
1820           perl examples/vertically-aligned/vertically-aligned.pl
1821
1822       This uses the Template Toolkit file "vertically-aligned.tt", and the
1823       CSS is defined in files "vertically-aligned.css" and
1824       "vertically-aligned-ie.css".
1825

SUPPORT

1827       Website:
1828
1829       <http://www.formfu.org>
1830
1831       Project Page:
1832
1833       http://code.google.com/p/html-formfu/ <http://code.google.com/p/html-
1834       formfu/>
1835
1836       Mailing list:
1837
1838       http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/html-formfu
1839       <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/html-formfu>
1840
1841       Mailing list archives:
1842
1843       http://lists.scsys.co.uk/pipermail/html-formfu/
1844       <http://lists.scsys.co.uk/pipermail/html-formfu/>
1845
1846       IRC:
1847
1848       "irc.perl.org", channel "#formfu"
1849
1850       The HTML::Widget archives
1851       http://lists.scsys.co.uk/pipermail/html-widget/
1852       <http://lists.scsys.co.uk/pipermail/html-widget/> between January and
1853       May 2007 also contain discussion regarding HTML::FormFu.
1854

BUGS

1856       Please submit bugs / feature requests to
1857       http://code.google.com/p/html-formfu/issues/list
1858       <http://code.google.com/p/html-formfu/issues/list> (preferred) or
1859       <http://rt.perl.org>.
1860

PATCHES

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

SUBVERSION REPOSITORY

1869       The publicly viewable subversion code repository is at
1870       http://html-formfu.googlecode.com/svn/trunk/HTML-FormFu <http://html-
1871       formfu.googlecode.com/svn/trunk/HTML-FormFu>.
1872
1873       If you wish to contribute, you'll need a google account. Then just ask
1874       on the mailing list for commit access, giving the email address your
1875       account uses.
1876
1877       If you wish to contribute but for some reason really don't want to sign
1878       up for a google account, please post patches to the mailing list
1879       (although you'll have to wait for someone to commit them).
1880
1881       If you have commit permissions, use the HTTPS repository url:
1882       https://html-formfu.googlecode.com/svn/trunk/HTML-FormFu <https://html-
1883       formfu.googlecode.com/svn/trunk/HTML-FormFu>
1884

SEE ALSO

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

AUTHORS

1893       Carl Franks
1894

CONTRIBUTORS

1896       Brian Cassidy
1897
1898       Ozum Eldogan
1899
1900       Ruben Fonseca
1901
1902       Ronald Kimball
1903
1904       Daisuke Maki
1905
1906       Andreas Marienborg
1907
1908       Mario Minati
1909
1910       Steve Nolte
1911
1912       Moritz Onken
1913
1914       Doug Orleans
1915
1916       Based on the original source code of HTML::Widget, by Sebastian Riedel,
1917       "sri@oook.de".
1918

LICENSE

1920       This library is free software, you can redistribute it and/or modify it
1921       under the same terms as Perl itself.
1922
1923
1924
1925perl v5.12.1                      2010-09-02                   HTML::FormFu(3)