Provided by: libhtml-formfu-perl_1.00000-1_all bug

NAME

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

SYNOPSIS

       Note: These examples make use of HTML::FormFu::Model::DBIC. As of "HTML::FormFu" v02.005,
       the HTML::FormFu::Model::DBIC module is not bundled with "HTML::FormFu" and is available
       in a stand-alone distribution.

           use HTML::FormFu;

           my $form = HTML::FormFu->new;

           $form->load_config_file('form.yml');

           $form->process( $cgi_query );

           if ( $form->submitted_and_valid ) {
               # do something with $form->params
           }
           else {
               # display the form
               $template->param( form => $form );
           }

       If you're using Catalyst, a more suitable example might be:

           package MyApp::Controller::User;
           use strict;
           use base 'Catalyst::Controller::HTML::FormFu';

           sub user : Chained CaptureArgs(1) {
               my ( $self, $c, $id ) = @_;

               my $rs = $c->model('Schema')->resultset('User');

               $c->stash->{user} = $rs->find( $id );

               return;
           }

           sub edit : Chained('user') Args(0) FormConfig {
               my ( $self, $c ) = @_;

               my $form = $c->stash->{form};
               my $user = $c->stash->{user};

               if ( $form->submitted_and_valid ) {

                   $form->model->update( $user );

                   $c->res->redirect( $c->uri_for( "/user/$id" ) );
                   return;
               }

               $form->model->default_values( $user )
                   if ! $form->submitted;

           }

       Note: Because "process" is automatically called for you by the Catalyst controller; if you
       make any modifications to the form within your action method, such as adding or changing
       elements, adding constraints, etc; you must call "process" again yourself before using
       "submitted_and_valid", any of the methods listed under "SUBMITTED FORM VALUES AND ERRORS"
       or "MODIFYING A SUBMITTED FORM", or rendering the form.

       Here's an example of a config file to create a basic login form (all examples here are
       YAML, but you can use any format supported by Config::Any), you can also create forms
       directly in your perl code, rather than using an external config file.

           ---
           action: /login
           indicator: submit
           auto_fieldset: 1

           elements:
             - type: Text
               name: user
               constraints:
                 - Required

             - type: Password
               name: pass
               constraints:
                 - Required

             - type: Submit
               name: submit

           constraints:
             - SingleValue

DESCRIPTION

       HTML::FormFu is a HTML form framework which aims to be as easy as possible to use for
       basic web forms, but with the power and flexibility to do anything else you might want to
       do (as long as it involves forms).

       You can configure almost any part of formfu's behaviour and output. By default formfu
       renders "XHTML 1.0 Strict" compliant markup, with as little extra markup as possible, but
       with sufficient CSS class names to allow for a wide-range of output styles to be generated
       by changing only the CSS.

       All methods listed below (except "new") can either be called as a normal method on your
       $form object, or as an option in your config file. Examples will mainly be shown in YAML
       config syntax.

       This documentation follows the convention that method arguments surrounded by square
       brackets "[]" are optional, and all other arguments are required.

BUILDING A FORM

   new
       Arguments: [\%options]

       Return Value: $form

       Create a new HTML::FormFu object.

       Any method which can be called on the HTML::FormFu object may instead be passed as an
       argument to "new".

           my $form = HTML::FormFu->new({
               action        => '/search',
               method        => 'GET',
               auto_fieldset => 1,
           });

   load_config_file
       Arguments: $filename

       Arguments: \@filenames

       Return Value: $form

       Accepts a filename or list of file names, whose filetypes should be of any format
       recognized by Config::Any.

       The content of each config file is passed to "populate", and so are added to the form.

       "load_config_file" may be called in a config file itself, so as to allow common settings
       to be kept in a single config file which may be loaded by any form.

           ---
           load_config_file:
             - file1
             - file2

       YAML multiple documents within a single file. The document start marker is a line
       containing 3 dashes. Multiple documents will be applied in order, just as if multiple
       filenames had been given.

       In the following example, multiple documents are taken advantage of to load another config
       file after the elements are added. (If this were a single document, the "load_config_file"
       would be called before "elements", regardless of its position in the file).

           ---
           elements:
             - name: one
             - name: two

           ---
           load_config_file: ext.yml

       Relative paths are resolved from the "config_file_path" directory if it is set, otherwise
       from the current working directory.

       See "BEST PRACTICES" for advice on organising config files.

   config_callback
       Arguments: \%options

       If defined, the arguments are used to create a Data::Visitor::Callback object during
       "load_config_file" which may be used to pre-process the config before it is sent to
       "populate".

       For example, the code below adds a callback to a form that will dynamically alter any
       config value ending in ".yml" to end in ".yaml" when you call "load_config_file":

           $form->config_callback({
             plain_value => sub {
               my( $visitor, $data ) = @_;
               s/\.yml/.yaml/;
             }
           });

       Default Value: not defined

       This method is a special 'inherited accessor', which means it can be set on the form, a
       block element or a single element. When the value is read, if no value is defined it
       automatically traverses the element's hierarchy of parents, through any block elements and
       up to the form, searching for a defined value.

   populate
       Arguments: \%options

       Return Value: $form

       Each option key/value passed may be any HTML::FormFu method-name and arguments.

       Provides a simple way to set multiple values, or add multiple elements to a form with a
       single method-call.

       Attempts to call the method-names in a semi-intelligent order (see the source of
       populate() in "HTML::FormFu::ObjectUtil" for details).

   default_values
       Arguments: \%defaults

       Return Value: $form

       Set multiple field's default values from a single hash-ref.

       The hash-ref's keys correspond to a form field's name, and the value is passed to the
       field's default method.

       This should be called after all fields have been added to the form, and before "process"
       is called (otherwise, call "process" again before rendering the form).

   config_file_path
       Arguments: $directory_name

       "config_file_path" defines where configuration files will be searched for, if an absolute
       path is not given to "load_config_file".

       Default Value: not defined

       This method is a special 'inherited accessor', which means it can be set on the form, a
       block element or a single element. When the value is read, if no value is defined it
       automatically traverses the element's hierarchy of parents, through any block elements and
       up to the form, searching for a defined value.

       Is an inheriting accessor.

   indicator
       Arguments: $field_name

       Arguments: \&coderef

       If "indicator" is set to a fieldname, "submitted" will return true if a value for that
       fieldname was submitted.

       If "indicator" is set to a code-ref, it will be called as a subroutine with the two
       arguments $form and $query, and its return value will be used as the return value for
       "submitted".

       If "indicator" is not set, "submitted" will return true if a value for any known fieldname
       was submitted.

   auto_fieldset
       Arguments: 1

       Arguments: \%options

       Return Value: $fieldset

       This setting is suitable for most basic forms, and means you can generally ignore adding
       fieldsets yourself.

       Calling "$form->auto_fieldset(1)" immediately adds a fieldset element to the form.
       Thereafter, "$form->elements()" will add all elements (except fieldsets) to that fieldset,
       rather than directly to the form.

       To be specific, the elements are added to the last fieldset on the form, so if you add
       another fieldset, any further elements will be added to that fieldset.

       Also, you may pass a hashref to auto_fieldset(), and this will be used to set defaults for
       the first fieldset created.

       A few examples and their output, to demonstrate:

       2 elements with no fieldset.

           ---
           elements:
             - type: Text
               name: foo
             - type: Text
               name: bar

           <form action="" method="post">
             <div class="text">
               <input name="foo" type="text" />
             </div>
             <div class="text">
               <input name="bar" type="text" />
             </div>
           </form>

       2 elements with an "auto_fieldset".

           ---
           auto_fieldset: 1
           elements:
             - type: Text
               name: foo
             - type: Text
               name: bar

           <form action="" method="post">
             <fieldset>
               <div class="text">
                 <input name="foo" type="text" />
               </div>
               <div class="text">
                 <input name="bar" type="text" />
               </div>
             </fieldset>
           </form>

       The 3rd element is within a new fieldset

           ---
           auto_fieldset: { id: fs }
           elements:
             - type: Text
               name: foo
             - type: Text
               name: bar
             - type: Fieldset
             - type: Text
               name: baz

           <form action="" method="post">
             <fieldset id="fs">
               <div class="text">
                 <input name="foo" type="text" />
               </div>
               <div class="text">
                 <input name="bar" type="text" />
               </div>
             </fieldset>
             <fieldset>
               <div class="text">
                 <input name="baz" type="text" />
               </div>
             </fieldset>
           </form>

       Because of this behaviour, if you want nested fieldsets you will have to add each nested
       fieldset directly to its intended parent.

           my $parent = $form->get_element({ type => 'Fieldset' });

           $parent->element('fieldset');

   form_error_message
       Arguments: $string

       Normally, input errors cause an error message to be displayed alongside the appropriate
       form field. If you'd also like a general error message to be displayed at the top of the
       form, you can set the message with "form_error_message".

       To set the CSS class for the message, see "form_error_message_class".

       To change the markup used to display the message, edit the "form_error_message" template
       file. See "render_method".

       Is an output accessor.

   force_error_message
       If true, forces the "form_error_message" to be displayed even if there are no field
       errors.

   default_args
       Arguments: \%defaults

       Set defaults which will be added to every element, constraint, etc. of the given type
       which is subsequently added to the form.

       For example, to make every "Text" element automatically have a size of 10, and make every
       "Strftime" deflator automatically get its strftime set to "%d/%m/%Y":

           default_args:
               elements:
                   Text:
                       size: 10
               deflators:
                   Strftime:
                       strftime: '%d/%m/%Y'

       An example to make all DateTime elements automatically get an appropriate Strftime
       deflator and a DateTime inflator:

           default_args:
               elements:
                   DateTime:
                       deflators:
                           type: Strftime
                           strftime: '%d-%m-%Y'
                       inflators:
                           type: DateTime
                           parser:
                               strptime: '%d-%m-%Y'

       Pseudo types

       As a special case, you can also use the "elements" keys "Block", "Field" and "Input" to
       match any element which inherits from HTML::FormFu::Element::Block or which "does"
       HTML::FormFu::Role::Element::Field or HTML::FormFu::Role::Element::Input.

       Alternatives

       Each "elements" key can contain an "any" list using the "|" divider: e.g.

           # apply the given class to any Element of type Password or Button
           default_args:
               elements:
                   'Password|Button':
                       attrs:
                           class: novalidate

       Match ancestor

       Each "elements" key list can contain a type starting with "+" to only match elements with
       an ancestor of the given type: e.g.

           # only apple the given class to an Input field within a Multi block
           default_args:
               elements:
                   'Input|+Multi':
                       attrs:
                           class: novalidate

       Don't match ancestor

       Each "elements" key list can contain a type starting with "-" to only match elements who
       do not have an ancestor of the given type: e.g.

           # apply the given class only to Input fields that are not in a Multi block
           default_args:
               elements:
                   'Input|-Multi':
                       attrs:
                           clasS: validate

       Order

       The arguments are applied in least- to most-specific order: "Block", "Field", "Input",
       $type. Within each of these, arguments are applied in order of shortest-first to longest-
       last.

       The "type" key must match the value returned by "type", e.g.  "type" in
       HTML::FormFu::Element. If, for example, you have a custom element outside of the
       "HTML::FormFu::Element::*" namespace, which you load via "$form->element({ type =>
       '+My::Custom::Element' })", the key given to "default_args" should not include the leading
       "+", as that is stripped-out of the returned "type()" value. Example:

           # don't include the leading '+' here
           default_args:
               elements:
                   'My::Custom::Element':
                       attrs:
                           class: whatever

           # do include the leading '+' here
           elements:
               - type: +My::Custom::Element

       Clashes

       "default_args" generates a single hashref to pass to "populate", merging arguments for
       each type in turn - meaning "populate" is only called once in total - not once for each
       type.  Because scalar values are not merged - this means later values will override
       earlier values: e.g.

           # Normally, calling $field->add_attrs({ class => 'input' })
           # then calling      $field->add_attrs({ class => 'not-in-multi' })
           # would result in both values being retained:
           #           class="input not-in-multi"
           #
           # However, default_args() creates a single data-structure to pass once
           # to populate(), so any scalar values will overwrite earlier ones
           # before they reach populate().
           #
           # The below example would result in the longest-matching key
           # overwriting any others:
           #           class="not-in-multi"
           #
           default_args:
               elements:
                   Input:
                       add_attrs:
                           class: input
                   'Input:-Multi':
                       add_attrs:
                           class: not-in-multi

       Strictness

       Note: Unlike the proper methods which have aliases, for example "elements" which is an
       alias for "element" - the keys given to "default_args" must be of the plural form, e.g.:

           default_args:
               elements:          {}
               deflators:         {}
               filters:           {}
               constraints:       {}
               inflators:         {}
               validators:        {}
               transformers:      {}
               output_processors: {}

   javascript
       If set, the contents will be rendered within a "script" tag, inside the top of the form.

   javascript_src
       Arguments: $url

       Arguments: \@urls

       Adds a "script" tag for each URL, immediately before any "javascript" section.

   stash
       Arguments: [\%private_stash]

       Return Value: \%stash

       Provides a hash-ref in which you can store any data you might want to associate with the
       form.

           ---
           stash:
             foo: value
             bar: value

   elements
   element
       Arguments: $type

       Arguments: \%options

       Return Value: $element

       Arguments: \@arrayref_of_types_or_options

       Return Value: @elements

       Adds a new element to the form. See "CORE FORM FIELDS" in HTML::FormFu::Element and "OTHER
       CORE ELEMENTS" in HTML::FormFu::Element for a list of core elements.

       If you want to load an element from a namespace other than "HTML::FormFu::Element::", you
       can use a fully qualified package-name by prefixing it with "+".

           ---
           elements:
             - type: +MyApp::CustomElement
               name: foo

       If a "type" is not provided in the "\%options", the default "Text" will be used.

       "element" is an alias for "elements".

   deflators
   deflator
       Arguments: $type

       Arguments: \%options

       Return Value: $deflator

       Arguments: \@arrayref_of_types_or_options

       Return Value: @deflators

       A deflator may be associated with any form field, and allows you to provide
       $field->default with a value which may be an object.

       If an object doesn't stringify to a suitable value for display, the deflator can ensure
       that the form field receives a suitable string value instead.

       See "CORE DEFLATORS" in HTML::FormFu::Deflator for a list of core deflators.

       If a "name" attribute isn't provided, a new deflator is created for and added to every
       field on the form.

       If you want to load a deflator in a namespace other than "HTML::FormFu::Deflator::", you
       can use a fully qualified package-name by prefixing it with "+".

       "deflator" is an alias for "deflators".

   insert_before
       Arguments: $new_element, $existing_element

       Return Value: $new_element

       The 1st argument must be the element you want added, the 2nd argument must be the existing
       element that the new element should be placed before.

           my $new = $form->element(\%specs);

           my $position = $form->get_element({ type => $type, name => $name });

           $form->insert_before( $new, $position );

       In the first line of the above example, the $new element is initially added to the end of
       the form. However, the "insert_before" method reparents the $new element, so it will no
       longer be on the end of the form. Because of this, if you try to copy an element from one
       form to another, it will 'steal' the element, instead of copying it. In this case, you
       must use "clone":

           my $new = $form1->get_element({ type => $type1, name => $name1 })
                           ->clone;

           my $position = $form2->get_element({ type => $type2, name => $name2 });

           $form2->insert_before( $new, $position );

   insert_after
       Arguments: $new_element, $existing_element

       Return Value: $new_element

       The 1st argument must be the element you want added, the 2nd argument must be the existing
       element that the new element should be placed after.

           my $new = $form->element(\%specs);

           my $position = $form->get_element({ type => $type, name => $name });

           $form->insert_after( $new, $position );

       In the first line of the above example, the $new element is initially added to the end of
       the form. However, the "insert_after" method reparents the $new element, so it will no
       longer be on the end of the form. Because of this, if you try to copy an element from one
       form to another, it will 'steal' the element, instead of copying it. In this case, you
       must use "clone":

           my $new = $form1->get_element({ type => $type1, name => $name1 })
                           ->clone;

           my $position = $form2->get_element({ type => $type2, name => $name2 });

           $form2->insert_after( $new, $position );

   remove_element
       Arguments: $element

       Return Value: $element

       Removes the $element from the form or block's array of children.

           $form->remove_element( $element );

       The orphaned element cannot be usefully used for anything until it is re-attached to a
       form or block with "insert_before" or "insert_after".

FORM LOGIC AND VALIDATION

       HTML::FormFu provides several stages for what is traditionally described as validation.
       These are:

       HTML::FormFu::Filter
       HTML::FormFu::Constraint
       HTML::FormFu::Inflator
       HTML::FormFu::Validator
       HTML::FormFu::Transformer

       The first stage, the filters, allow for cleanup of user-input, such as encoding, or
       removing leading/trailing whitespace, or removing non-digit characters from a creditcard
       number.

       All of the following stages allow for more complex processing, and each of them have a
       mechanism to allow exceptions to be thrown, to represent input errors. In each stage, all
       form fields must be processed without error for the next stage to proceed. If there were
       any errors, the form should be re-displayed to the user, to allow them to input correct
       values.

       Constraints are intended for low-level validation of values, such as "is this an
       integer?", "is this value within bounds?" or "is this a valid email address?".

       Inflators are intended to allow a value to be turned into an appropriate object. The
       resulting object will be passed to subsequent Validators and Transformers, and will also
       be returned by "params" and "param".

       Validators are intended for higher-level validation, such as business-logic and database
       constraints such as "is this username unique?".  Validators are only run if all
       Constraints and Inflators have run without errors. It is expected that most Validators
       will be application-specific, and so each will be implemented as a separate class written
       by the HTML::FormFu user.

   filters
   filter
       Arguments: $type

       Arguments: \%options

       Return Value: $filter

       Arguments: \@arrayref_of_types_or_options

       Return Value: @filters

       If you provide a "name" or "names" value, the filter will be added to just that named
       field.  If you do not provide a "name" or "names" value, the filter will be added to all
       fields already attached to the form.

       See "CORE FILTERS" in HTML::FormFu::Filter for a list of core filters.

       If you want to load a filter in a namespace other than "HTML::FormFu::Filter::", you can
       use a fully qualified package-name by prefixing it with "+".

       "filter" is an alias for "filters".

   constraints
   constraint
       Arguments: $type

       Arguments: \%options

       Return Value: $constraint

       Arguments: \@arrayref_of_types_or_options

       Return Value: @constraints

       See "CORE CONSTRAINTS" in HTML::FormFu::Constraint for a list of core constraints.

       If a "name" attribute isn't provided, a new constraint is created for and added to every
       field on the form.

       If you want to load a constraint in a namespace other than "HTML::FormFu::Constraint::",
       you can use a fully qualified package-name by prefixing it with "+".

       "constraint" is an alias for "constraints".

   inflators
   inflator
       Arguments: $type

       Arguments: \%options

       Return Value: $inflator

       Arguments: \@arrayref_of_types_or_options

       Return Value: @inflators

       See "CORE INFLATORS" in HTML::FormFu::Inflator for a list of core inflators.

       If a "name" attribute isn't provided, a new inflator is created for and added to every
       field on the form.

       If you want to load an inflator in a namespace other than "HTML::FormFu::Inflator::", you
       can use a fully qualified package-name by prefixing it with "+".

       "inflator" is an alias for "inflators".

   validators
   validator
       Arguments: $type

       Arguments: \%options

       Return Value: $validator

       Arguments: \@arrayref_of_types_or_options

       Return Value: @validators

       See "CORE VALIDATORS" in HTML::FormFu::Validator for a list of core validators.

       If a "name" attribute isn't provided, a new validator is created for and added to every
       field on the form.

       If you want to load a validator in a namespace other than "HTML::FormFu::Validator::", you
       can use a fully qualified package-name by prefixing it with "+".

       "validator" is an alias for "validators".

   transformers
   transformer
       Arguments: $type

       Arguments: \%options

       Return Value: $transformer

       Arguments: \@arrayref_of_types_or_options

       Return Value: @transformers

       See "CORE TRANSFORMERS" in HTML::FormFu::Transformer for a list of core transformers.

       If a "name" attribute isn't provided, a new transformer is created for and added to every
       field on the form.

       If you want to load a transformer in a namespace other than "HTML::FormFu::Transformer::",
       you can use a fully qualified package-name by prefixing it with "+".

       "transformer" is an alias for "transformers".

CHANGING DEFAULT BEHAVIOUR

   render_processed_value
       The default behaviour when re-displaying a form after a submission, is that the field
       contains the original unchanged user-submitted value.

       If "render_processed_value" is true, the field value will be the final result after all
       Filters, Inflators and Transformers have been run.  Deflators will also be run on the
       value.

       If you set this on a field with an Inflator, but without an equivalent Deflator, you
       should ensure that the Inflators stringify back to a usable value, so as not to confuse /
       annoy the user.

       Default Value: false

       This method is a special 'inherited accessor', which means it can be set on the form, a
       block element or a single element. When the value is read, if no value is defined it
       automatically traverses the element's hierarchy of parents, through any block elements and
       up to the form, searching for a defined value.

       Is an inheriting accessor.

   force_errors
       Force a constraint to fail, regardless of user input.

       If this is called at runtime, after the form has already been processed, you must called
       "process" in HTML::FormFu again before redisplaying the form to the user.

       Default Value: false

       This method is a special 'inherited accessor', which means it can be set on the form, a
       block element, an element or a single constraint. When the value is read, if no value is
       defined it automatically traverses the element's hierarchy of parents, through any block
       elements and up to the form, searching for a defined value.

       Is an inheriting accessor.

   params_ignore_underscore
       If true, causes "params", "param" and "valid" to ignore any fields whose name starts with
       an underscore "_".

       The field is still processed as normal, and errors will cause "submitted_and_valid" to
       return false.

       Default Value: false

FORM ATTRIBUTES

       All attributes are added to the rendered form's start tag.

   attributes
           # Example
           ---
           attributes:
             id: form
             class: fancy_form

       Is an attribute accessor.

   id
       Is an attribute short-cut.

   action
       Default Value: ""

       Get or set the action associated with the form. The default is no action, which causes
       most browsers to submit to the current URI.

       Is an attribute short-cut.

   enctype
       Get or set the encoding type of the form. Valid values are
       "application/x-www-form-urlencoded" and "multipart/form-data".

       If the form contains a File element, the enctype is automatically set to
       "multipart/form-data".

       Is an attribute short-cut.

   method
       Default Value: "post"

       Get or set the method used to submit the form. Can be set to either "post" or "get".

       Is an attribute short-cut.

   title
       Get or set the form's title attribute.

       Is an attribute short-cut.

CSS CLASSES

   form_error_message_class
       Class attribute for the error message displayed at the top of the form.

       See "form_error_message"

LOCALIZATION

   languages
       Arguments: [\@languages]

       A list of languages which will be passed to the localization object.

       Default Value: ['en']

   localize_class
       Arguments: [$class_name]

       Classname to be used for the default localization object.

       Default Value: 'HTML::FormFu::I18N'

   localize
   loc
       Arguments: [$key, @arguments]

       Compatible with the "maketext" method in Locale::Maketext.

   locale
       Arguments: $locale

       Currently only used by HTML::FormFu::Deflator::FormatNumber and
       HTML::FormFu::Filter::FormatNumber.

       This method is a special 'inherited accessor', which means it can be set on the form, a
       block element or a single element. When the value is read, if no value is defined it
       automatically traverses the element's hierarchy of parents, through any block elements and
       up to the form, searching for a defined value.

       Is an inheriting accessor.

PROCESSING A FORM

   query
       Arguments: [$query_object]

       Arguments: \%params

       Provide a CGI compatible query object or a hash-ref of submitted names/values.
       Alternatively, the query object can be passed directly to the "process" object.

   query_type
       Arguments: [$query_type]

       Set which module is being used to provide the "query".

       The Catalyst::Controller::HTML::FormFu automatically sets this to "Catalyst".

       Valid values are "CGI", "Catalyst" and "CGI::Simple".

       Default Value: 'CGI'

   process
       Arguments: [$query_object]

       Arguments: [\%params]

       Process the provided query object or input values. "process" must be called before calling
       any of the methods listed under "SUBMITTED FORM VALUES AND ERRORS" and "MODIFYING A
       SUBMITTED FORM".

       "process" must also be called at least once before printing the form or calling "render"
       or "render_data".

       Note to users of Catalyst::Controller::HTML::FormFu: Because "process" is automatically
       called for you by the Catalyst controller; if you make any modifications to the form
       within your action method, such as adding or changing elements, adding constraints, etc;
       you must call "process" again yourself before using "submitted_and_valid", any of the
       methods listed under "SUBMITTED FORM VALUES AND ERRORS" or "MODIFYING A SUBMITTED FORM",
       or rendering the form.

SUBMITTED FORM VALUES AND ERRORS

   submitted
       Returns true if the form has been submitted. See "indicator" for details on how this is
       computed.

   submitted_and_valid
       Shorthand for "$form->submitted && !$form->has_errors"

   params
       Return Value: \%params

       Returns a hash-ref of all valid input for which there were no errors.

   param_value
       Arguments: $field_name

       A more reliable, recommended version of "param". Guaranteed to always return a single
       value, regardless of whether it's called in list context or not. If multiple values were
       submitted, this only returns the first value. If the value is invalid or the form was not
       submitted, it returns "undef". This makes it suitable for use in list context, where a
       single value is required.

           $db->update({
               name    => $form->param_value('name'),
               address => $form->param_value('address),
           });

   param_array
       Arguments: $field_name

       Guaranteed to always return an array-ref of values, regardless of context and regardless
       of whether multiple values were submitted or not. If the value is invalid or the form was
       not submitted, it returns an empty array-ref.

   param_list
       Arguments: $field_name

       Guaranteed to always return a list of values, regardless of context. If the value is
       invalid or the form was not submitted, it returns an empty list.

   param
       Arguments: [$field_name]

       Return Value: $input_value

       Return Value: @valid_names

       No longer recommended for use, as its behaviour is hard to predict. Use "param_value",
       "param_array" or "param_list" instead.

       A (readonly) method similar to that of CGI's.

       If a field name is given, in list-context returns any valid values submitted for that
       field, and in scalar-context returns only the first of any valid values submitted for that
       field.

       If no argument is given, returns a list of all valid input field names without errors.

       Passing more than 1 argument is a fatal error.

   valid
       Arguments: [$field_name]

       Return Value: @valid_names

       Return Value: $bool

       If a field name if given, returns "true" if that field had no errors and "false" if there
       were errors.

       If no argument is given, returns a list of all valid input field names without errors.

   has_errors
       Arguments: [$field_name]

       Return Value: @names

       Return Value: $bool

       If a field name if given, returns "true" if that field had errors and "false" if there
       were no errors.

       If no argument is given, returns a list of all input field names with errors.

   get_errors
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: \@errors

       Returns an array-ref of exception objects from all fields in the form.

       Accepts both "name", "type" and "stage" arguments to narrow the returned results.

           $form->get_errors({
               name  => 'foo',
               type  => 'Regex',
               stage => 'constraint'
           });

   get_error
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: $error

       Accepts the same arguments as "get_errors", but only returns the first error found.

MODEL / DATABASE INTERACTION

       See HTML::FormFu::Model for further details and available models.

   default_model
       Arguments: $model_name

       Default Value: 'DBIC'

   model
       Arguments: [$model_name]

       Return Value: $model

   model_config
       Arguments: \%config

MODIFYING A SUBMITTED FORM

   add_valid
       Arguments: $name, $value

       Return Value: $value

       The provided value replaces any current value for the named field. This value will be
       returned in subsequent calls to "params" and "param" and the named field will be included
       in calculations for "valid".

   clear_errors
       Deletes all errors from a submitted form.

RENDERING A FORM

   render
       Return Value: $string

       You must call "process" once after building the form, and before calling "render".

   start
       Return Value: $string

       Returns the form start tag, and any output of "form_error_message" and "javascript".

   end
       Return Value: $string

       Returns the form end tag.

   hidden_fields
       Return Value: $string

       Returns all hidden form fields.

PLUGIN SYSTEM

       "HTML::FormFu" provides a plugin-system that allows plugins to be easily added to a form
       or element, to change the default behaviour or output.

       See HTML::FormFu::Plugin for details.

ADVANCED CUSTOMISATION

       By default, formfu renders "XHTML 1.0 Strict" compliant markup, with as little extra
       markup as possible, but with sufficient CSS class names to allow for a wide-range of
       output styles to be generated by changing only the CSS.

       If you wish to customise the markup, you'll need to tell HTML::FormFu to use an external
       rendering engine, such as Template Toolkit or Template::Alloy. See "render_method" and
       "tt_module" for details.

       Even if you set HTML::FormFu to use Template::Toolkit to render, the forms, HTML::FormFu
       can still be used in conjunction with whichever other templating system you prefer to use
       for your own page layouts, whether it's HTML::Template: "<TMPL_VAR form>", Petal: "<form
       tal:replace="form"></form>" or Template::Magic: "<!-- {form} -->".

       As of "HTML::FormFu v1.00", TT is no longer listed a required prerequisite - so you'll
       need to install it manually if you with to use the template files.

   render_method
       Default Value: "string"

       Can be set to "tt" to generate the form with external template files.

       To customise the markup, you'll need a copy of the template files, local to your
       application. See "Installing the TT templates" in HTML::FormFu::Manual::Cookbook for
       further details.

       You can customise the markup for a single element by setting that element's
       "render_method" to "tt", while the rest of the form uses the default "string" render-
       method. Note though, that if you try setting the form or a Block's "render_method" to
       "tt", and then set a child element's "render_method" to "string", that setting will be
       ignored, and the child elements will still use the "tt" render-method.

           ---
           elements:
             - name: foo
               render_method: tt
               filename: custom_field

             - name: bar

           # in this example, 'foo' will use a custom template,
           # while bar will use the default 'string' rendering method

       This method is a special 'inherited accessor', which means it can be set on the form, a
       block element or a single element. When the value is read, if no value is defined it
       automatically traverses the element's hierarchy of parents, through any block elements and
       up to the form, searching for a defined value.

       Is an inheriting accessor.

   filename
       Change the template filename used for the form.

       Default Value: "form"

   tt_args
       Arguments: [\%constructor_arguments]

       Accepts a hash-ref of arguments passed to "render_method", which is called internally by
       "render".

       Within tt_args, the keys "RELATIVE" and "RECURSION" are overridden to always be true, as
       these are a basic requirement for the Template engine.

       The system directory containing HTML::FormFu's template files is always added to the end
       of "INCLUDE_PATH", so that the core template files will be found. You only need to set
       this yourself if you have your own copy of the template files for customisation purposes.

       This method is a special 'inherited accessor', which means it can be set on the form, a
       block element or a single element. When the value is read, if no value is defined it
       automatically traverses the element's hierarchy of parents, through any block elements and
       up to the form, searching for a defined value.

   add_tt_args
       Arguments: [\%constructor_arguments]

       Ensures that the hash-ref argument is merged with any existing hash-ref value of
       "tt_args".

   tt_module
       Default Value: Template

       The module used when "render_method" is set to "tt". Should provide an interface
       compatible with Template.

       This method is a special 'inherited accessor', which means it can be set on the form, a
       block element or a single element. When the value is read, if no value is defined it
       automatically traverses the element's hierarchy of parents, through any block elements and
       up to the form, searching for a defined value.

   render_data
       Usually called implicitly by "render". Returns the data structure that would normally be
       passed onto the "string" or "tt" render-methods.

       As with "render", you must call "process" once after building the form, and before calling
       "render_data".

   render_data_non_recursive
       Like "render_data", but doesn't include the data for any child-elements.

INTROSPECTION

   get_fields
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: \@elements

       Returns all fields in the form (specifically, all elements which have a true "is_field" in
       HTML::FormFu::Element value).

       Accepts both "name" and "type" arguments to narrow the returned results.

           $form->get_fields({
               name => 'foo',
               type => 'Radio',
           });

       Accepts also an Regexp to search for results.

           $form->get_elements({
               name => qr/oo/,
           });

   get_field
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: $element

       Accepts the same arguments as "get_fields", but only returns the first field found.

   get_elements
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: \@elements

       Returns all top-level elements in the form (not recursive).  See "get_all_elements" for a
       recursive version.

       Accepts both "name" and "type" arguments to narrow the returned results.

           $form->get_elements({
               name => 'foo',
               type => 'Radio',
           });

       Accepts also an Regexp to search for results.

           $form->get_elements({
               name => qr/oo/,
           });

   get_element
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: $element

       Accepts the same arguments as "get_elements", but only returns the first element found.

       See "get_all_element" for a recursive version.

   get_all_elements
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: \@elements

       Returns all elements in the form recursively.

       Optionally accepts both "name" and "type" arguments to narrow the returned results.

           # return all Text elements

           $form->get_all_elements({
               type => 'Text',
           });

       Accepts also an Regexp to search for results.

           $form->get_elements({
               name => qr/oo/,
           });

       See "get_elements" for a non-recursive version.

   get_all_element
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: $element

       Accepts the same arguments as "get_all_elements", but only returns the first element
       found.

           # return the first Text field found, regardless of whether it's
           # within a fieldset or not

           $form->get_all_element({
               type => 'Text',
           });

       Accepts also an Regexp to search for results.

           $form->get_elements({
               name => qr/oo/,
           });

       See "get_all_elements" for a non-recursive version.

   get_deflators
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: \@deflators

       Returns all top-level deflators from all fields.

       Accepts both "name" and "type" arguments to narrow the returned results.

           $form->get_deflators({
               name => 'foo',
               type => 'Strftime',
           });

   get_deflator
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: $element

       Accepts the same arguments as "get_deflators", but only returns the first deflator found.

   get_filters
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: \@filters

       Returns all top-level filters from all fields.

       Accepts both "name" and "type" arguments to narrow the returned results.

           $form->get_filters({
               name => 'foo',
               type => 'LowerCase',
           });

   get_filter
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: $filter

       Accepts the same arguments as "get_filters", but only returns the first filter found.

   get_constraints
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: \@constraints

       Returns all constraints from all fields.

       Accepts both "name" and "type" arguments to narrow the returned results.

           $form->get_constraints({
               name => 'foo',
               type => 'Equal',
           });

   get_constraint
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: $constraint

       Accepts the same arguments as "get_constraints", but only returns the first constraint
       found.

   get_inflators
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: \@inflators

       Returns all inflators from all fields.

       Accepts both "name" and "type" arguments to narrow the returned results.

           $form->get_inflators({
               name => 'foo',
               type => 'DateTime',
           });

   get_inflator
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: $inflator

       Accepts the same arguments as "get_inflators", but only returns the first inflator found.

   get_validators
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: \@validators

       Returns all validators from all fields.

       Accepts both "name" and "type" arguments to narrow the returned results.

           $form->get_validators({
               name => 'foo',
               type => 'Callback',
           });

   get_validator
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: $validator

       Accepts the same arguments as "get_validators", but only returns the first validator
       found.

   get_transformers
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: \@transformers

       Returns all transformers from all fields.

       Accepts both "name" and "type" arguments to narrow the returned results.

           $form->get_transformers({
               name => 'foo',
               type => 'Callback',
           });

   get_transformer
       Arguments: [%options]

       Arguments: [\%options]

       Return Value: $transformer

       Accepts the same arguments as "get_transformers", but only returns the first transformer
       found.

   clone
       Returns a deep clone of the <$form> object.

       Because of scoping issues, code references (such as in Callback constraints) are copied
       instead of cloned.

ATTRIBUTE ACCESSORS

       For the basic method, e.g. "/attributes":

       Arguments: [%attributes]

       Arguments: [\%attributes]

       Return Value: $form

       As a special case, if no arguments are passed, the attributes hash-ref is returned. This
       allows the following idioms.

           # set a value
           $form->attributes->{id} = 'form';

           # delete all attributes
           %{ $form->attributes } = ();

       All methods documented as 'attribute accessors' also have the following variants
       generated:

       *_xml can be used as a setter, and ensures that its argument is not XML-escaped in the
       rendered form.

       *_loc can he used as a setter, and passes the arguments through "localize".

       "add_*" can be used to append a word to an attribute without overwriting any already-
       existing value.

           # Example
           $form->attributes({ class => 'fancy' });
           $form->add_attributes({ class => 'pants' });
           # class="fancy pants"

       "add_*_xml", like "add_*", but ensures it doesn't get XML-escaped.

       "add_*_loc", like "add_*", but passing the arguments through "localize".

       "del_*" can be used to remove a word from an attribute value.

           # Example
           $form->attributes({ class => 'fancy pants' });
           $form->del_attributes({ class => 'pants' });
           # class="fancy"

       "del_*_xml", like "del_*", but ensures it doesn't get XML-escaped.

       "del_*_loc", like "del_*", but passing the arguments through "localize".

       Also, any attribute method-name which contains the word "attributes" also has aliases
       created for all these variants, with the word "attributes" replaced by "attrs".

           # For example, the attributes() method would have all these variant
           # methods available

           $form->attributes({ class => 'fancy' });
           $form->attributes_xml({ title => '<b>fancy</b>' });
           $form->attributes_loc({ title => 'fancy' });
           $form->add_attributes({ class => 'fancy' });
           $form->add_attributes_xml({ title => '<b>fancy</b>' });
           $form->add_attributes_loc({ title => 'fancy' });
           $form->del_attributes({ class => 'fancy' });
           $form->del_attributes_xml({ title => '<b>fancy</b>' });
           $form->del_attributes_loc({ title => 'fancy' });

           # Because the method contains the word 'attributes', it also gets the
           # following short-forms

           $form->attrs({ class => 'fancy' });
           $form->attrs_xml({ title => '<b>fancy</b>' });
           $form->attrs_loc({ title => 'fancy' });
           $form->add_attrs({ class => 'fancy' });
           $form->add_attrs_xml({ title => '<b>fancy</b>' });
           $form->add_attrs_loc({ title => 'fancy' });
           $form->del_attrs({ class => 'fancy' });
           $form->del_attrs_xml({ title => '<b>fancy</b>' });
           $form->del_attrs_loc({ title => 'fancy' });

ATTRIBUTE SHORT-CUTS

       All methods documented as 'attribute short-cuts' are short-cuts to directly access
       individual attribute key/values.

           # Example
           $form->id( 'login' );
           $id = $form->id;

           # is equivalent to:
           $form->attributes({ id => 'login' });
           $id = $form->attributes->{id};

       All attribute short-cuts also have a *_xml variant.

           # Example
           $form->id_xml( $xml );

           # is equivalent to:
           $form->attributes_xml({ id => $xml });

       All attribute short-cuts also have a *_loc variant.

           # Example
           $form->title_loc( $key );

           # is equivalent to:
           $form->attributes_loc({ title => $key });

INHERITING ACCESSORS

       All methods documented as 'inheriting accessors' can be set on the form, a block element
       or a single field element.  When the value is read, if no value is defined it
       automatically traverses the element's hierarchy of parents, searching for a defined value.

       All inherited accessors also have a *_no_inherit variant, which can be used as a getter to
       fetch any defined value, without traversing the hierarchy of parents. This variant cannot
       be used as a setter.

       E.g., the "auto_id" has a variant named "auto_id_no_inherit".

OUTPUT ACCESSORS

       All methods documented as 'output accessors' also have *_xml and *_loc variants.

       The *_xml variant can be used as a setter, and ensures that its argument is not XML-
       escaped in the rendered form.

       The *_loc variant can be used as a setter, and passes the arguments through "localize".

       E.g., the label method has variants named "label_xml" and "label_loc".

BOOLEAN ATTRIBUTE ACCESSORS

       To support boolean attributes, whose value should either be equal to the attribute name,
       or empty. Any true value will switch the attribute 'on', any false value will remove the
       attribute.

           # Example

           $field->autofocus(1);
           # equivalent to:
           $field->attributes({ autofocus => 'autofocus' });

           $field->autofocus(0);;
           # equivalent to:
           delete $field->attributes->{autofocus};

ATTRIBUTE SUBSTITUTIONS

       Some attributes support character substitutions: the following substitutions are possible:

           %f # $form->id
           %n # $field->name
           %t # lc( $field->type )
           %r # $block->repeatable_count
           %s # $error->stage

       These allow each field to have consistent attributes, while remaining unique.

DEPRECATION POLICY

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

RESTORING LEGACY HTML CLASSES

       "v1.00" dropped most of the default HTML class-names, with the intention that each
       application should define just what it needs, without needing to reset unwanted options
       first. We also gain the benefit of less markup being generated, speeding up both render
       and HTTP tranfers.

       To restore the previous behaviour, set the following options.

       If you're using best practices, you'll only need to set these once per-application in your
       app-wide config file.

           ---
           auto_container_class: '%t'
           auto_container_label_class: 'label'
           auto_container_comment_class: 'comment'
           auto_comment_class: 'comment'
           auto_container_error_class: 'error'
           auto_container_per_error_class: 'error_%s_%t'
           auto_error_class: 'error_message error_%s_%t'

REMOVED METHODS

       See also "REMOVED METHODS" in HTML::FormFu::Element.

   element_defaults
       Has been removed; see "default_args" instead.

   model_class
       Has been removed; use "default_model" instead.

   defaults_from_model
       Has been removed; use "default_values" in HTML::FormFu::Model instead.

   save_to_model
       Has been removed; use "update" in HTML::FormFu::Model instead.

BEST PRACTICES

       It is advisable to keep application-wide (or global) settings in a single config file,
       which should be loaded by each form.

       See "load_config_file".

COOKBOOK

       HTML::FormFu::Manual::Cookbook

   UNICODE
       HTML::FormFu::Manual::Unicode

EXAMPLES

   vertically-aligned CSS
       The distribution directory "examples/vertically-aligned" contains a form with example CSS
       for a "vertically aligned" theme.

       This can be viewed by opening the file "vertically-aligned.html" in a web-browser.

       If you wish to experiment with making changes, the form is defined in file
       "vertically-aligned.yml", and the HTML file can be updated with any changes by running the
       following command (while in the distribution root directory).

           perl examples/vertically-aligned/vertically-aligned.pl

       This uses the Template Toolkit file "vertically-aligned.tt", and the CSS is defined in
       files "vertically-aligned.css" and "vertically-aligned-ie.css".

SUPPORT

       Website:

       <http://www.formfu.org>

       Project Page:

       <http://code.google.com/p/html-formfu/>

       Mailing list:

       <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/html-formfu>

       Mailing list archives:

       <http://lists.scsys.co.uk/pipermail/html-formfu/>

       IRC:

       "irc.perl.org", channel "#formfu"

       The HTML::Widget archives <http://lists.scsys.co.uk/pipermail/html-widget/> between
       January and May 2007 also contain discussion regarding HTML::FormFu.

BUGS

       Please submit bug reports to the Debian Bug Tracker. You can use reportbug(1) to do so
       interactively. A list of reported bugs can be found at
       <http://bugs.debian.org/libhtml-formfu-perl>.

       For upstream bug reports look at <http://code.google.com/p/html-formfu/issues/list>
       (preferred) or <http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML-FormFu>.

PATCHES

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

GITHUB REPOSITORY

       This module's sourcecode is maintained in a git repository at
       <git://github.com/fireartist/HTML-FormFu.git>

       The project page is <https://github.com/fireartist/HTML-FormFu>

SEE ALSO

       HTML::FormFu::Imager

       Catalyst::Controller::HTML::FormFu

       HTML::FormFu::Model::DBIC

AUTHORS

       Carl Franks

CONTRIBUTORS

       Brian Cassidy

       Ozum Eldogan

       Ruben Fonseca

       Ronald Kimball

       Daisuke Maki

       Andreas Marienborg

       Mario Minati

       Steve Nolte

       Moritz Onken

       Doug Orleans

       Matthias Dietrich

       Based on the original source code of HTML::Widget, by Sebastian Riedel, "sri@oook.de".

LICENSE

       This library is free software, you can redistribute it and/or modify it under the same
       terms as Perl itself.

PERL GAME

       Play the MMO written in perl: <http://www.lacunaexpanse.com>!