NAME

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

VERSION

    version 2.07

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 Moose;
        extends '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. Many hooks are provided to add
    programatically-generated CSS class names, to allow for a wide-range of
    output styles to be generated by changing only the CSS.

    Basic customisation of the markup is possible via the layout and
    multi_layout methods. This allows you to reorder the position of
    various parts of each field - such as the label, comment, error
    messages and the input tag - as well as inserting any other arbitrary
    tags you may wish.

    If this is not sufficient, you can make completely personalise the
    markup by telling 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 transfers.

    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'

DEPRECATED METHODS

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

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

    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 bugs / feature requests to
    https://github.com/FormFu/HTML-FormFu/issues (preferred) or
    http://rt.perl.org.

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/FormFu/HTML-FormFu.git

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

SEE ALSO

    HTML::FormFu::Imager

    Catalyst::Controller::HTML::FormFu

    HTML::FormFu::Model::DBIC

CONTRIBUTORS

    Brian Cassidy

    Ozum Eldogan

    Ruben Fonseca

    Ronald Kimball

    Daisuke Maki

    Andreas Marienborg

    Mario Minati

    Steve Nolte

    Moritz Onken

    Doug Orleans

    Matthias Dietrich

    Dean Hamstead

    Karen Etheridge

    Nigel Metheringham

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

AUTHOR

    Carl Franks <cpan@fireartist.com>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2018 by Carl Franks.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.