.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HTML::FormFu 3pm"
.TH HTML::FormFu 3pm 2024-04-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
HTML::FormFu \- HTML Form Creation, Rendering and Validation Framework
.SH VERSION
.IX Header "VERSION"
version 2.07
.SH SYNOPSIS
.IX Header "SYNOPSIS"
Note: These examples make use of HTML::FormFu::Model::DBIC. As of
\&\f(CW\*(C`HTML::FormFu\*(C'\fR v02.005, the HTML::FormFu::Model::DBIC module is
not bundled with \f(CW\*(C`HTML::FormFu\*(C'\fR and is available in a stand-alone
distribution.
.PP
.Vb 1
\&    use HTML::FormFu;
\&
\&    my $form = HTML::FormFu\->new;
\&
\&    $form\->load_config_file(\*(Aqform.yml\*(Aq);
\&
\&    $form\->process( $cgi_query );
\&
\&    if ( $form\->submitted_and_valid ) {
\&        # do something with $form\->params
\&    }
\&    else {
\&        # display the form
\&        $template\->param( form => $form );
\&    }
.Ve
.PP
If you're using Catalyst, a more suitable example might be:
.PP
.Vb 3
\&    package MyApp::Controller::User;
\&    use Moose;
\&    extends \*(AqCatalyst::Controller::HTML::FormFu\*(Aq;
\&
\&    sub user : Chained CaptureArgs(1) {
\&        my ( $self, $c, $id ) = @_;
\&
\&        my $rs = $c\->model(\*(AqSchema\*(Aq)\->resultset(\*(AqUser\*(Aq);
\&
\&        $c\->stash\->{user} = $rs\->find( $id );
\&
\&        return;
\&    }
\&
\&    sub edit : Chained(\*(Aquser\*(Aq) 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;
\&
\&    }
.Ve
.PP
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.
.PP
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.
.PP
.Vb 4
\&    \-\-\-
\&    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
.Ve
.SH DESCRIPTION
.IX Header "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).
.PP
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.
.PP
All methods listed below (except "new") can either be called as a normal
method on your \f(CW$form\fR object, or as an option in your config file. Examples
will mainly be shown in YAML config syntax.
.PP
This documentation follows the convention that method arguments surrounded
by square brackets \f(CW\*(C`[]\*(C'\fR are \fIoptional\fR, and all other arguments are
required.
.SH "BUILDING A FORM"
.IX Header "BUILDING A FORM"
.SS new
.IX Subsection "new"
Arguments: [\e%options]
.PP
Return Value: \f(CW$form\fR
.PP
Create a new HTML::FormFu object.
.PP
Any method which can be called on the HTML::FormFu object may
instead be passed as an argument to "new".
.PP
.Vb 5
\&    my $form = HTML::FormFu\->new({
\&        action        => \*(Aq/search\*(Aq,
\&        method        => \*(AqGET\*(Aq,
\&        auto_fieldset => 1,
\&    });
.Ve
.SS load_config_file
.IX Subsection "load_config_file"
Arguments: \f(CW$filename\fR
.PP
Arguments: \e@filenames
.PP
Return Value: \f(CW$form\fR
.PP
Accepts a filename or list of file names, whose filetypes should be of any
format recognized by Config::Any.
.PP
The content of each config file is passed to "populate", and so are added
to the form.
.PP
"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.
.PP
.Vb 4
\&    \-\-\-
\&    load_config_file:
\&      \- file1
\&      \- file2
.Ve
.PP
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.
.PP
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 \f(CW\*(C`load_config_file\*(C'\fR would be called before
\&\f(CW\*(C`elements\*(C'\fR, regardless of its position in the file).
.PP
.Vb 4
\&    \-\-\-
\&    elements:
\&      \- name: one
\&      \- name: two
\&
\&    \-\-\-
\&    load_config_file: ext.yml
.Ve
.PP
Relative paths are resolved from the "config_file_path" directory if
it is set, otherwise from the current working directory.
.PP
See "BEST PRACTICES" for advice on organising config files.
.SS config_callback
.IX Subsection "config_callback"
Arguments: \e%options
.PP
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".
.PP
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":
.PP
.Vb 6
\&    $form\->config_callback({
\&      plain_value => sub {
\&        my( $visitor, $data ) = @_;
\&        s/\e.yml/.yaml/;
\&      }
\&    });
.Ve
.PP
Default Value: not defined
.PP
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.
.SS populate
.IX Subsection "populate"
Arguments: \e%options
.PP
Return Value: \f(CW$form\fR
.PP
Each option key/value passed may be any HTML::FormFu
method-name and arguments.
.PP
Provides a simple way to set multiple values, or add multiple elements to
a form with a single method-call.
.PP
Attempts to call the method-names in a semi-intelligent order (see
the source of \fBpopulate()\fR in \f(CW\*(C`HTML::FormFu::ObjectUtil\*(C'\fR for details).
.SS default_values
.IX Subsection "default_values"
Arguments: \e%defaults
.PP
Return Value: \f(CW$form\fR
.PP
Set multiple field's default values from a single hash-ref.
.PP
The hash-ref's keys correspond to a form field's name, and the value is
passed to the field's default method.
.PP
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).
.SS config_file_path
.IX Subsection "config_file_path"
Arguments: \f(CW$directory_name\fR
.PP
"config_file_path" defines where configuration files will be
searched for, if an absolute path is not given to
"load_config_file".
.PP
Default Value: not defined
.PP
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.
.PP
Is an inheriting accessor.
.SS indicator
.IX Subsection "indicator"
Arguments: \f(CW$field_name\fR
.PP
Arguments: \e&coderef
.PP
If "indicator" is set to a fieldname, "submitted" will return true if
a value for that fieldname was submitted.
.PP
If "indicator" is set to a code-ref, it will be called as a subroutine
with the two arguments \f(CW$form\fR and \f(CW$query\fR, and its return value will be
used as the return value for "submitted".
.PP
If "indicator" is not set, "submitted" will return true if a value for
any known fieldname was submitted.
.SS auto_fieldset
.IX Subsection "auto_fieldset"
Arguments: 1
.PP
Arguments: \e%options
.PP
Return Value: \f(CW$fieldset\fR
.PP
This setting is suitable for most basic forms, and means you can generally
ignore adding fieldsets yourself.
.PP
Calling \f(CW\*(C`$form\->auto_fieldset(1)\*(C'\fR immediately adds a fieldset element to
the form. Thereafter, \f(CW\*(C`$form\->elements()\*(C'\fR will add all elements (except
fieldsets) to that fieldset, rather than directly to the form.
.PP
To be specific, the elements are added to the \fIlast\fR fieldset on the form,
so if you add another fieldset, any further elements will be added to that
fieldset.
.PP
Also, you may pass a hashref to \fBauto_fieldset()\fR, and this will be used
to set defaults for the first fieldset created.
.PP
A few examples and their output, to demonstrate:
.PP
2 elements with no fieldset.
.PP
.Vb 6
\&    \-\-\-
\&    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>
.Ve
.PP
2 elements with an "auto_fieldset".
.PP
.Vb 7
\&    \-\-\-
\&    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>
.Ve
.PP
The 3rd element is within a new fieldset
.PP
.Vb 10
\&    \-\-\-
\&    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>
.Ve
.PP
Because of this behaviour, if you want nested fieldsets you will have to add
each nested fieldset directly to its intended parent.
.PP
.Vb 1
\&    my $parent = $form\->get_element({ type => \*(AqFieldset\*(Aq });
\&
\&    $parent\->element(\*(Aqfieldset\*(Aq);
.Ve
.SS form_error_message
.IX Subsection "form_error_message"
Arguments: \f(CW$string\fR
.PP
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".
.PP
To set the CSS class for the message, see "form_error_message_class".
.PP
To change the markup used to display the message, edit the
\&\f(CW\*(C`form_error_message\*(C'\fR template file. See "render_method".
.PP
Is an output accessor.
.SS force_error_message
.IX Subsection "force_error_message"
If true, forces the "form_error_message" to be displayed even if there are
no field errors.
.SS default_args
.IX Subsection "default_args"
Arguments: \e%defaults
.PP
Set defaults which will be added to every element, constraint, etc. of the
given type which is subsequently added to the form.
.PP
For example, to make every \f(CW\*(C`Text\*(C'\fR element automatically have a size of
\&\f(CW10\fR, and make every \f(CW\*(C`Strftime\*(C'\fR deflator automatically get its strftime
set to \f(CW\*(C`%d/%m/%Y\*(C'\fR:
.PP
.Vb 7
\&    default_args:
\&        elements:
\&            Text:
\&                size: 10
\&        deflators:
\&            Strftime:
\&                strftime: \*(Aq%d/%m/%Y\*(Aq
.Ve
.PP
An example to make all DateTime elements automatically get an appropriate
Strftime deflator and a DateTime inflator:
.PP
.Vb 10
\&    default_args:
\&        elements:
\&            DateTime:
\&                deflators:
\&                    type: Strftime
\&                    strftime: \*(Aq%d\-%m\-%Y\*(Aq
\&                inflators:
\&                    type: DateTime
\&                    parser:
\&                        strptime: \*(Aq%d\-%m\-%Y\*(Aq
.Ve
.PP
\fIPseudo types\fR
.IX Subsection "Pseudo types"
.PP
As a special case, you can also use the \f(CW\*(C`elements\*(C'\fR keys \f(CW\*(C`Block\*(C'\fR, \f(CW\*(C`Field\*(C'\fR
and \f(CW\*(C`Input\*(C'\fR to match any element which inherits from
HTML::FormFu::Element::Block or which \f(CW\*(C`does\*(C'\fR
HTML::FormFu::Role::Element::Field or
HTML::FormFu::Role::Element::Input.
.PP
\fIAlternatives\fR
.IX Subsection "Alternatives"
.PP
Each \f(CW\*(C`elements\*(C'\fR key can contain an \f(CW\*(C`any\*(C'\fR list using the \f(CW\*(C`|\*(C'\fR divider: e.g.
.PP
.Vb 6
\&    # apply the given class to any Element of type Password or Button
\&    default_args:
\&        elements:
\&            \*(AqPassword|Button\*(Aq:
\&                attrs:
\&                    class: novalidate
.Ve
.PP
\fIMatch ancestor\fR
.IX Subsection "Match ancestor"
.PP
Each \f(CW\*(C`elements\*(C'\fR key list can contain a type starting with \f(CW\*(C`+\*(C'\fR to only
match elements with an ancestor of the given type: e.g.
.PP
.Vb 6
\&    # only apple the given class to an Input field within a Multi block
\&    default_args:
\&        elements:
\&            \*(AqInput|+Multi\*(Aq:
\&                attrs:
\&                    class: novalidate
.Ve
.PP
\fIDon't match ancestor\fR
.IX Subsection "Don't match ancestor"
.PP
Each \f(CW\*(C`elements\*(C'\fR key list can contain a type starting with \f(CW\*(C`\-\*(C'\fR to only
match elements who do not have an ancestor of the given type: e.g.
.PP
.Vb 6
\&    # apply the given class only to Input fields that are not in a Multi block
\&    default_args:
\&        elements:
\&            \*(AqInput|\-Multi\*(Aq:
\&                attrs:
\&                    clasS: validate
.Ve
.PP
\fIOrder\fR
.IX Subsection "Order"
.PP
The arguments are applied in least\- to most-specific order:
\&\f(CW\*(C`Block\*(C'\fR, \f(CW\*(C`Field\*(C'\fR, \f(CW\*(C`Input\*(C'\fR, \f(CW$type\fR. Within each of these, arguments are
applied in order of shortest-first to longest-last.
.PP
The \f(CW\*(C`type\*(C'\fR key must match the value returned by \f(CW\*(C`type\*(C'\fR, e.g.
"type" in HTML::FormFu::Element. If, for example, you have a custom element
outside of the \f(CW\*(C`HTML::FormFu::Element::*\*(C'\fR namespace, which you load via
\&\f(CW\*(C`$form\->element({ type => \*(Aq+My::Custom::Element\*(Aq })\*(C'\fR, the key given to
"default_args" should \fBnot\fR include the leading \f(CW\*(C`+\*(C'\fR, as that is
stripped-out of the returned \f(CWtype()\fR value. Example:
.PP
.Vb 6
\&    # don\*(Aqt include the leading \*(Aq+\*(Aq here
\&    default_args:
\&        elements:
\&            \*(AqMy::Custom::Element\*(Aq:
\&                attrs:
\&                    class: whatever
\&
\&    # do include the leading \*(Aq+\*(Aq here
\&    elements:
\&        \- type: +My::Custom::Element
.Ve
.PP
\fIClashes\fR
.IX Subsection "Clashes"
.PP
"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 \fBnot\fR merged \- this means later values will
override earlier values: e.g.
.PP
.Vb 10
\&    # Normally, calling $field\->add_attrs({ class => \*(Aqinput\*(Aq })
\&    # then calling      $field\->add_attrs({ class => \*(Aqnot\-in\-multi\*(Aq })
\&    # 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
\&            \*(AqInput:\-Multi\*(Aq:
\&                add_attrs:
\&                    class: not\-in\-multi
.Ve
.PP
\fIStrictness\fR
.IX Subsection "Strictness"
.PP
Note: Unlike the proper methods which have aliases, for example "elements"
which is an alias for "element" \- the keys given to \f(CW\*(C`default_args\*(C'\fR must
be of the plural form, e.g.:
.PP
.Vb 9
\&    default_args:
\&        elements:          {}
\&        deflators:         {}
\&        filters:           {}
\&        constraints:       {}
\&        inflators:         {}
\&        validators:        {}
\&        transformers:      {}
\&        output_processors: {}
.Ve
.SS javascript
.IX Subsection "javascript"
If set, the contents will be rendered within a \f(CW\*(C`script\*(C'\fR tag, inside the top
of the form.
.SS javascript_src
.IX Subsection "javascript_src"
Arguments: \f(CW$url\fR
.PP
Arguments: \e@urls
.PP
Adds a \f(CW\*(C`script\*(C'\fR tag for each URL, immediately before any "javascript"
section.
.SS stash
.IX Subsection "stash"
Arguments: [\e%private_stash]
.PP
Return Value: \e%stash
.PP
Provides a hash-ref in which you can store any data you might want to
associate with the form.
.PP
.Vb 4
\&    \-\-\-
\&    stash:
\&      foo: value
\&      bar: value
.Ve
.SS elements
.IX Subsection "elements"
.SS element
.IX Subsection "element"
Arguments: \f(CW$type\fR
.PP
Arguments: \e%options
.PP
Return Value: \f(CW$element\fR
.PP
Arguments: \e@arrayref_of_types_or_options
.PP
Return Value: \f(CW@elements\fR
.PP
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.
.PP
If you want to load an element from a namespace other than
\&\f(CW\*(C`HTML::FormFu::Element::\*(C'\fR, you can use a fully qualified package-name by
prefixing it with \f(CW\*(C`+\*(C'\fR.
.PP
.Vb 4
\&    \-\-\-
\&    elements:
\&      \- type: +MyApp::CustomElement
\&        name: foo
.Ve
.PP
If a \f(CW\*(C`type\*(C'\fR is not provided in the \f(CW\*(C`\e%options\*(C'\fR, the default \f(CW\*(C`Text\*(C'\fR will
be used.
.PP
"element" is an alias for "elements".
.SS deflators
.IX Subsection "deflators"
.SS deflator
.IX Subsection "deflator"
Arguments: \f(CW$type\fR
.PP
Arguments: \e%options
.PP
Return Value: \f(CW$deflator\fR
.PP
Arguments: \e@arrayref_of_types_or_options
.PP
Return Value: \f(CW@deflators\fR
.PP
A deflator may be associated with any form field,
and allows you to provide
\&\f(CW$field\fR\->default with a value
which may be an object.
.PP
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.
.PP
See "CORE DEFLATORS" in HTML::FormFu::Deflator for a list of core deflators.
.PP
If a \f(CW\*(C`name\*(C'\fR attribute isn't provided, a new deflator is created for and
added to every field on the form.
.PP
If you want to load a deflator in a namespace other than
\&\f(CW\*(C`HTML::FormFu::Deflator::\*(C'\fR, you can use a fully qualified package-name by
prefixing it with \f(CW\*(C`+\*(C'\fR.
.PP
"deflator" is an alias for "deflators".
.SS insert_before
.IX Subsection "insert_before"
Arguments: \f(CW$new_element\fR, \f(CW$existing_element\fR
.PP
Return Value: \f(CW$new_element\fR
.PP
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.
.PP
.Vb 1
\&    my $new = $form\->element(\e%specs);
\&
\&    my $position = $form\->get_element({ type => $type, name => $name });
\&
\&    $form\->insert_before( $new, $position );
.Ve
.PP
In the first line of the above example, the \f(CW$new\fR element is initially
added to the end of the form. However, the \f(CW\*(C`insert_before\*(C'\fR method
reparents the \f(CW$new\fR 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 \f(CW\*(C`clone\*(C'\fR:
.PP
.Vb 2
\&    my $new = $form1\->get_element({ type => $type1, name => $name1 })
\&                    \->clone;
\&
\&    my $position = $form2\->get_element({ type => $type2, name => $name2 });
\&
\&    $form2\->insert_before( $new, $position );
.Ve
.SS insert_after
.IX Subsection "insert_after"
Arguments: \f(CW$new_element\fR, \f(CW$existing_element\fR
.PP
Return Value: \f(CW$new_element\fR
.PP
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.
.PP
.Vb 1
\&    my $new = $form\->element(\e%specs);
\&
\&    my $position = $form\->get_element({ type => $type, name => $name });
\&
\&    $form\->insert_after( $new, $position );
.Ve
.PP
In the first line of the above example, the \f(CW$new\fR element is initially
added to the end of the form. However, the \f(CW\*(C`insert_after\*(C'\fR method
reparents the \f(CW$new\fR 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 \f(CW\*(C`clone\*(C'\fR:
.PP
.Vb 2
\&    my $new = $form1\->get_element({ type => $type1, name => $name1 })
\&                    \->clone;
\&
\&    my $position = $form2\->get_element({ type => $type2, name => $name2 });
\&
\&    $form2\->insert_after( $new, $position );
.Ve
.SS remove_element
.IX Subsection "remove_element"
Arguments: \f(CW$element\fR
.PP
Return Value: \f(CW$element\fR
.PP
Removes the \f(CW$element\fR from the form or block's array of children.
.PP
.Vb 1
\&    $form\->remove_element( $element );
.Ve
.PP
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".
.SH "FORM LOGIC AND VALIDATION"
.IX Header "FORM LOGIC AND VALIDATION"
HTML::FormFu provides several stages for what is
traditionally described as \fIvalidation\fR. These are:
.IP HTML::FormFu::Filter 4
.IX Item "HTML::FormFu::Filter"
.PD 0
.IP HTML::FormFu::Constraint 4
.IX Item "HTML::FormFu::Constraint"
.IP HTML::FormFu::Inflator 4
.IX Item "HTML::FormFu::Inflator"
.IP HTML::FormFu::Validator 4
.IX Item "HTML::FormFu::Validator"
.IP HTML::FormFu::Transformer 4
.IX Item "HTML::FormFu::Transformer"
.PD
.PP
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.
.PP
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.
.PP
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?".
.PP
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".
.PP
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.
.SS filters
.IX Subsection "filters"
.SS filter
.IX Subsection "filter"
Arguments: \f(CW$type\fR
.PP
Arguments: \e%options
.PP
Return Value: \f(CW$filter\fR
.PP
Arguments: \e@arrayref_of_types_or_options
.PP
Return Value: \f(CW@filters\fR
.PP
If you provide a \f(CW\*(C`name\*(C'\fR or \f(CW\*(C`names\*(C'\fR value, the filter will be added to
just that named field.
If you do not provide a \f(CW\*(C`name\*(C'\fR or \f(CW\*(C`names\*(C'\fR value, the filter will be added
to all fields already attached to the form.
.PP
See "CORE FILTERS" in HTML::FormFu::Filter for a list of core filters.
.PP
If you want to load a filter in a namespace other than
\&\f(CW\*(C`HTML::FormFu::Filter::\*(C'\fR, you can use a fully qualified package-name by
prefixing it with \f(CW\*(C`+\*(C'\fR.
.PP
"filter" is an alias for "filters".
.SS constraints
.IX Subsection "constraints"
.SS constraint
.IX Subsection "constraint"
Arguments: \f(CW$type\fR
.PP
Arguments: \e%options
.PP
Return Value: \f(CW$constraint\fR
.PP
Arguments: \e@arrayref_of_types_or_options
.PP
Return Value: \f(CW@constraints\fR
.PP
See "CORE CONSTRAINTS" in HTML::FormFu::Constraint for a list of core
constraints.
.PP
If a \f(CW\*(C`name\*(C'\fR attribute isn't provided, a new constraint is created for and
added to every field on the form.
.PP
If you want to load a constraint in a namespace other than
\&\f(CW\*(C`HTML::FormFu::Constraint::\*(C'\fR, you can use a fully qualified package-name by
prefixing it with \f(CW\*(C`+\*(C'\fR.
.PP
"constraint" is an alias for "constraints".
.SS inflators
.IX Subsection "inflators"
.SS inflator
.IX Subsection "inflator"
Arguments: \f(CW$type\fR
.PP
Arguments: \e%options
.PP
Return Value: \f(CW$inflator\fR
.PP
Arguments: \e@arrayref_of_types_or_options
.PP
Return Value: \f(CW@inflators\fR
.PP
See "CORE INFLATORS" in HTML::FormFu::Inflator for a list of core inflators.
.PP
If a \f(CW\*(C`name\*(C'\fR attribute isn't provided, a new inflator is created for and
added to every field on the form.
.PP
If you want to load an inflator in a namespace other than
\&\f(CW\*(C`HTML::FormFu::Inflator::\*(C'\fR, you can use a fully qualified package-name by
prefixing it with \f(CW\*(C`+\*(C'\fR.
.PP
"inflator" is an alias for "inflators".
.SS validators
.IX Subsection "validators"
.SS validator
.IX Subsection "validator"
Arguments: \f(CW$type\fR
.PP
Arguments: \e%options
.PP
Return Value: \f(CW$validator\fR
.PP
Arguments: \e@arrayref_of_types_or_options
.PP
Return Value: \f(CW@validators\fR
.PP
See "CORE VALIDATORS" in HTML::FormFu::Validator for a list of core
validators.
.PP
If a \f(CW\*(C`name\*(C'\fR attribute isn't provided, a new validator is created for and
added to every field on the form.
.PP
If you want to load a validator in a namespace other than
\&\f(CW\*(C`HTML::FormFu::Validator::\*(C'\fR, you can use a fully qualified package-name by
prefixing it with \f(CW\*(C`+\*(C'\fR.
.PP
"validator" is an alias for "validators".
.SS transformers
.IX Subsection "transformers"
.SS transformer
.IX Subsection "transformer"
Arguments: \f(CW$type\fR
.PP
Arguments: \e%options
.PP
Return Value: \f(CW$transformer\fR
.PP
Arguments: \e@arrayref_of_types_or_options
.PP
Return Value: \f(CW@transformers\fR
.PP
See "CORE TRANSFORMERS" in HTML::FormFu::Transformer for a list of core
transformers.
.PP
If a \f(CW\*(C`name\*(C'\fR attribute isn't provided, a new transformer is created for and
added to every field on the form.
.PP
If you want to load a transformer in a namespace other than
\&\f(CW\*(C`HTML::FormFu::Transformer::\*(C'\fR, you can use a fully qualified package-name by
prefixing it with \f(CW\*(C`+\*(C'\fR.
.PP
"transformer" is an alias for "transformers".
.SH "CHANGING DEFAULT BEHAVIOUR"
.IX Header "CHANGING DEFAULT BEHAVIOUR"
.SS render_processed_value
.IX Subsection "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.
.PP
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.
.PP
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.
.PP
Default Value: false
.PP
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.
.PP
Is an inheriting accessor.
.SS force_errors
.IX Subsection "force_errors"
Force a constraint to fail, regardless of user input.
.PP
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.
.PP
Default Value: false
.PP
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.
.PP
Is an inheriting accessor.
.SS params_ignore_underscore
.IX Subsection "params_ignore_underscore"
If true, causes "params", "param" and "valid" to ignore any fields
whose name starts with an underscore \f(CW\*(C`_\*(C'\fR.
.PP
The field is still processed as normal, and errors will cause
"submitted_and_valid" to return false.
.PP
Default Value: false
.SH "FORM ATTRIBUTES"
.IX Header "FORM ATTRIBUTES"
All attributes are added to the rendered form's start tag.
.SS attributes
.IX Subsection "attributes"
.Vb 5
\&    # Example
\&    \-\-\-
\&    attributes:
\&      id: form
\&      class: fancy_form
.Ve
.PP
Is an attribute accessor.
.SS id
.IX Subsection "id"
Is an attribute short-cut.
.SS action
.IX Subsection "action"
Default Value: ""
.PP
Get or set the action associated with the form. The default is no action,
which causes most browsers to submit to the current URI.
.PP
Is an attribute short-cut.
.SS enctype
.IX Subsection "enctype"
Get or set the encoding type of the form. Valid values are
\&\f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR and \f(CW\*(C`multipart/form\-data\*(C'\fR.
.PP
If the form contains a File element, the enctype is automatically set to
\&\f(CW\*(C`multipart/form\-data\*(C'\fR.
.PP
Is an attribute short-cut.
.SS method
.IX Subsection "method"
Default Value: "post"
.PP
Get or set the method used to submit the form. Can be set to either "post"
or "get".
.PP
Is an attribute short-cut.
.SS title
.IX Subsection "title"
Get or set the form's title attribute.
.PP
Is an attribute short-cut.
.SH "CSS CLASSES"
.IX Header "CSS CLASSES"
.SS form_error_message_class
.IX Subsection "form_error_message_class"
Class attribute for the error message displayed at the top of the form.
.PP
See "form_error_message"
.SH LOCALIZATION
.IX Header "LOCALIZATION"
.SS languages
.IX Subsection "languages"
Arguments: [\e@languages]
.PP
A list of languages which will be passed to the localization object.
.PP
Default Value: ['en']
.SS localize_class
.IX Subsection "localize_class"
Arguments: [$class_name]
.PP
Classname to be used for the default localization object.
.PP
Default Value: 'HTML::FormFu::I18N'
.SS localize
.IX Subsection "localize"
.SS loc
.IX Subsection "loc"
Arguments: [$key, \f(CW@arguments\fR]
.PP
Compatible with the \f(CW\*(C`maketext\*(C'\fR method in Locale::Maketext.
.SS locale
.IX Subsection "locale"
Arguments: \f(CW$locale\fR
.PP
Currently only used by HTML::FormFu::Deflator::FormatNumber and
HTML::FormFu::Filter::FormatNumber.
.PP
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.
.PP
Is an inheriting accessor.
.SH "PROCESSING A FORM"
.IX Header "PROCESSING A FORM"
.SS query
.IX Subsection "query"
Arguments: [$query_object]
.PP
Arguments: \e%params
.PP
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.
.SS query_type
.IX Subsection "query_type"
Arguments: [$query_type]
.PP
Set which module is being used to provide the "query".
.PP
The Catalyst::Controller::HTML::FormFu automatically sets this to
\&\f(CW\*(C`Catalyst\*(C'\fR.
.PP
Valid values are \f(CW\*(C`CGI\*(C'\fR, \f(CW\*(C`Catalyst\*(C'\fR and \f(CW\*(C`CGI::Simple\*(C'\fR.
.PP
Default Value: 'CGI'
.SS process
.IX Subsection "process"
Arguments: [$query_object]
.PP
Arguments: [\e%params]
.PP
Process the provided query object or input values. \f(CW\*(C`process\*(C'\fR must be called
before calling any of the methods listed under
"SUBMITTED FORM VALUES AND ERRORS" and "MODIFYING A SUBMITTED FORM".
.PP
\&\f(CW\*(C`process\*(C'\fR must also be called at least once before printing the form or
calling "render" or "render_data".
.PP
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.
.SH "SUBMITTED FORM VALUES AND ERRORS"
.IX Header "SUBMITTED FORM VALUES AND ERRORS"
.SS submitted
.IX Subsection "submitted"
Returns true if the form has been submitted. See "indicator" for details
on how this is computed.
.SS submitted_and_valid
.IX Subsection "submitted_and_valid"
Shorthand for \f(CW\*(C`$form\->submitted && !$form\->has_errors\*(C'\fR
.SS params
.IX Subsection "params"
Return Value: \e%params
.PP
Returns a hash-ref of all valid input for which there were no errors.
.SS param_value
.IX Subsection "param_value"
Arguments: \f(CW$field_name\fR
.PP
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 \f(CW\*(C`undef\*(C'\fR. This makes it
suitable for use in list context, where a single value is required.
.PP
.Vb 4
\&    $db\->update({
\&        name    => $form\->param_value(\*(Aqname\*(Aq),
\&        address => $form\->param_value(\*(Aqaddress),
\&    });
.Ve
.SS param_array
.IX Subsection "param_array"
Arguments: \f(CW$field_name\fR
.PP
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.
.SS param_list
.IX Subsection "param_list"
Arguments: \f(CW$field_name\fR
.PP
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.
.SS param
.IX Subsection "param"
Arguments: [$field_name]
.PP
Return Value: \f(CW$input_value\fR
.PP
Return Value: \f(CW@valid_names\fR
.PP
No longer recommended for use, as its behaviour is hard to predict. Use
"param_value", "param_array" or "param_list" instead.
.PP
A (readonly) method similar to that of CGI's.
.PP
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.
.PP
If no argument is given, returns a list of all valid input field names
without errors.
.PP
Passing more than 1 argument is a fatal error.
.SS valid
.IX Subsection "valid"
Arguments: [$field_name]
.PP
Return Value: \f(CW@valid_names\fR
.PP
Return Value: \f(CW$bool\fR
.PP
If a field name if given, returns \f(CW\*(C`true\*(C'\fR if that field had no errors and
\&\f(CW\*(C`false\*(C'\fR if there were errors.
.PP
If no argument is given, returns a list of all valid input field names
without errors.
.SS has_errors
.IX Subsection "has_errors"
Arguments: [$field_name]
.PP
Return Value: \f(CW@names\fR
.PP
Return Value: \f(CW$bool\fR
.PP
If a field name if given, returns \f(CW\*(C`true\*(C'\fR if that field had errors and
\&\f(CW\*(C`false\*(C'\fR if there were no errors.
.PP
If no argument is given, returns a list of all input field names with errors.
.SS get_errors
.IX Subsection "get_errors"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \e@errors
.PP
Returns an array-ref of exception objects from all fields in the form.
.PP
Accepts both \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`type\*(C'\fR and \f(CW\*(C`stage\*(C'\fR arguments to narrow the returned
results.
.PP
.Vb 5
\&    $form\->get_errors({
\&        name  => \*(Aqfoo\*(Aq,
\&        type  => \*(AqRegex\*(Aq,
\&        stage => \*(Aqconstraint\*(Aq
\&    });
.Ve
.SS get_error
.IX Subsection "get_error"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \f(CW$error\fR
.PP
Accepts the same arguments as "get_errors", but only returns the first
error found.
.SH "MODEL / DATABASE INTERACTION"
.IX Header "MODEL / DATABASE INTERACTION"
See HTML::FormFu::Model for further details and available models.
.SS default_model
.IX Subsection "default_model"
Arguments: \f(CW$model_name\fR
.PP
Default Value: 'DBIC'
.SS model
.IX Subsection "model"
Arguments: [$model_name]
.PP
Return Value: \f(CW$model\fR
.SS model_config
.IX Subsection "model_config"
Arguments: \e%config
.SH "MODIFYING A SUBMITTED FORM"
.IX Header "MODIFYING A SUBMITTED FORM"
.SS add_valid
.IX Subsection "add_valid"
Arguments: \f(CW$name\fR, \f(CW$value\fR
.PP
Return Value: \f(CW$value\fR
.PP
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".
.SS clear_errors
.IX Subsection "clear_errors"
Deletes all errors from a submitted form.
.SH "RENDERING A FORM"
.IX Header "RENDERING A FORM"
.SS render
.IX Subsection "render"
Return Value: \f(CW$string\fR
.PP
You must call "process" once after building the form, and before calling
"render".
.SS start
.IX Subsection "start"
Return Value: \f(CW$string\fR
.PP
Returns the form start tag, and any output of "form_error_message" and
"javascript".
.SS end
.IX Subsection "end"
Return Value: \f(CW$string\fR
.PP
Returns the form end tag.
.SS hidden_fields
.IX Subsection "hidden_fields"
Return Value: \f(CW$string\fR
.PP
Returns all hidden form fields.
.SH "PLUGIN SYSTEM"
.IX Header "PLUGIN SYSTEM"
\&\f(CW\*(C`HTML::FormFu\*(C'\fR provides a plugin-system that allows plugins to be easily
added to a form or element, to change the default behaviour or output.
.PP
See HTML::FormFu::Plugin for details.
.SH "ADVANCED CUSTOMISATION"
.IX Header "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.
.PP
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.
.PP
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.
.PP
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: \f(CW\*(C`<TMPL_VAR form>\*(C'\fR,
Petal: \f(CW\*(C`<form tal:replace="form"></form>\*(C'\fR
or Template::Magic: \f(CW\*(C`<!\-\- {form} \-\->\*(C'\fR.
.PP
As of \f(CW\*(C`HTML::FormFu v1.00\*(C'\fR, TT is no longer listed a required
prerequisite \- so you'll need to install it manually if you with to use the
template files.
.SS render_method
.IX Subsection "render_method"
Default Value: \f(CW\*(C`string\*(C'\fR
.PP
Can be set to \f(CW\*(C`tt\*(C'\fR to generate the form with external template files.
.PP
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.
.PP
You can customise the markup for a single element by setting that element's
"render_method" to \f(CW\*(C`tt\*(C'\fR, while the rest of the form uses the default
\&\f(CW\*(C`string\*(C'\fR render-method. Note though, that if you try setting the form or a
Block's "render_method" to \f(CW\*(C`tt\*(C'\fR, and then set a child element's
"render_method" to \f(CW\*(C`string\*(C'\fR, that setting will be ignored, and the child
elements will still use the \f(CW\*(C`tt\*(C'\fR render-method.
.PP
.Vb 5
\&    \-\-\-
\&    elements:
\&      \- name: foo
\&        render_method: tt
\&        filename: custom_field
\&
\&      \- name: bar
\&
\&    # in this example, \*(Aqfoo\*(Aq will use a custom template,
\&    # while bar will use the default \*(Aqstring\*(Aq rendering method
.Ve
.PP
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.
.PP
Is an inheriting accessor.
.SS filename
.IX Subsection "filename"
Change the template filename used for the form.
.PP
Default Value: "form"
.SS tt_args
.IX Subsection "tt_args"
Arguments: [\e%constructor_arguments]
.PP
Accepts a hash-ref of arguments passed to "render_method", which is called
internally by "render".
.PP
Within tt_args, the keys \f(CW\*(C`RELATIVE\*(C'\fR and \f(CW\*(C`RECURSION\*(C'\fR are overridden to always
be true, as these are a basic requirement for the Template engine.
.PP
The system directory containing HTML::FormFu's template files is always
added to the end of \f(CW\*(C`INCLUDE_PATH\*(C'\fR, 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.
.PP
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.
.SS add_tt_args
.IX Subsection "add_tt_args"
Arguments: [\e%constructor_arguments]
.PP
Ensures that the hash-ref argument is merged with any existing hash-ref
value of "tt_args".
.SS tt_module
.IX Subsection "tt_module"
Default Value: Template
.PP
The module used when "render_method" is set to \f(CW\*(C`tt\*(C'\fR. Should provide an
interface compatible with Template.
.PP
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.
.SS render_data
.IX Subsection "render_data"
Usually called implicitly by "render". Returns the data structure that
would normally be passed onto the \f(CW\*(C`string\*(C'\fR or \f(CW\*(C`tt\*(C'\fR render-methods.
.PP
As with "render", you must call "process" once after building the form,
and before calling "render_data".
.SS render_data_non_recursive
.IX Subsection "render_data_non_recursive"
Like "render_data", but doesn't include the data for any child-elements.
.SH INTROSPECTION
.IX Header "INTROSPECTION"
.SS get_fields
.IX Subsection "get_fields"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \e@elements
.PP
Returns all fields in the form (specifically, all elements which have a true
"is_field" in HTML::FormFu::Element value).
.PP
Accepts both \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`type\*(C'\fR arguments to narrow the returned results.
.PP
.Vb 4
\&    $form\->get_fields({
\&        name => \*(Aqfoo\*(Aq,
\&        type => \*(AqRadio\*(Aq,
\&    });
.Ve
.PP
Accepts also an Regexp to search for results.
.PP
.Vb 3
\&    $form\->get_elements({
\&        name => qr/oo/,
\&    });
.Ve
.SS get_field
.IX Subsection "get_field"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \f(CW$element\fR
.PP
Accepts the same arguments as "get_fields", but only returns the first
field found.
.SS get_elements
.IX Subsection "get_elements"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \e@elements
.PP
Returns all top-level elements in the form (not recursive).
See "get_all_elements" for a recursive version.
.PP
Accepts both \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`type\*(C'\fR arguments to narrow the returned results.
.PP
.Vb 4
\&    $form\->get_elements({
\&        name => \*(Aqfoo\*(Aq,
\&        type => \*(AqRadio\*(Aq,
\&    });
.Ve
.PP
Accepts also an Regexp to search for results.
.PP
.Vb 3
\&    $form\->get_elements({
\&        name => qr/oo/,
\&    });
.Ve
.SS get_element
.IX Subsection "get_element"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \f(CW$element\fR
.PP
Accepts the same arguments as "get_elements", but only returns the first
element found.
.PP
See "get_all_element" for a recursive version.
.SS get_all_elements
.IX Subsection "get_all_elements"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \e@elements
.PP
Returns all elements in the form recursively.
.PP
Optionally accepts both \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`type\*(C'\fR arguments to narrow the returned
results.
.PP
.Vb 1
\&    # return all Text elements
\&
\&    $form\->get_all_elements({
\&        type => \*(AqText\*(Aq,
\&    });
.Ve
.PP
Accepts also an Regexp to search for results.
.PP
.Vb 3
\&    $form\->get_elements({
\&        name => qr/oo/,
\&    });
.Ve
.PP
See "get_elements" for a non-recursive version.
.SS get_all_element
.IX Subsection "get_all_element"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \f(CW$element\fR
.PP
Accepts the same arguments as "get_all_elements", but only returns the
first element found.
.PP
.Vb 2
\&    # return the first Text field found, regardless of whether it\*(Aqs
\&    # within a fieldset or not
\&
\&    $form\->get_all_element({
\&        type => \*(AqText\*(Aq,
\&    });
.Ve
.PP
Accepts also an Regexp to search for results.
.PP
.Vb 3
\&    $form\->get_elements({
\&        name => qr/oo/,
\&    });
.Ve
.PP
See "get_all_elements" for a non-recursive version.
.SS get_deflators
.IX Subsection "get_deflators"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \e@deflators
.PP
Returns all top-level deflators from all fields.
.PP
Accepts both \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`type\*(C'\fR arguments to narrow the returned results.
.PP
.Vb 4
\&    $form\->get_deflators({
\&        name => \*(Aqfoo\*(Aq,
\&        type => \*(AqStrftime\*(Aq,
\&    });
.Ve
.SS get_deflator
.IX Subsection "get_deflator"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \f(CW$element\fR
.PP
Accepts the same arguments as "get_deflators", but only returns the first
deflator found.
.SS get_filters
.IX Subsection "get_filters"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \e@filters
.PP
Returns all top-level filters from all fields.
.PP
Accepts both \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`type\*(C'\fR arguments to narrow the returned results.
.PP
.Vb 4
\&    $form\->get_filters({
\&        name => \*(Aqfoo\*(Aq,
\&        type => \*(AqLowerCase\*(Aq,
\&    });
.Ve
.SS get_filter
.IX Subsection "get_filter"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \f(CW$filter\fR
.PP
Accepts the same arguments as "get_filters", but only returns the first
filter found.
.SS get_constraints
.IX Subsection "get_constraints"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \e@constraints
.PP
Returns all constraints from all fields.
.PP
Accepts both \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`type\*(C'\fR arguments to narrow the returned results.
.PP
.Vb 4
\&    $form\->get_constraints({
\&        name => \*(Aqfoo\*(Aq,
\&        type => \*(AqEqual\*(Aq,
\&    });
.Ve
.SS get_constraint
.IX Subsection "get_constraint"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \f(CW$constraint\fR
.PP
Accepts the same arguments as "get_constraints", but only returns the
first constraint found.
.SS get_inflators
.IX Subsection "get_inflators"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \e@inflators
.PP
Returns all inflators from all fields.
.PP
Accepts both \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`type\*(C'\fR arguments to narrow the returned results.
.PP
.Vb 4
\&    $form\->get_inflators({
\&        name => \*(Aqfoo\*(Aq,
\&        type => \*(AqDateTime\*(Aq,
\&    });
.Ve
.SS get_inflator
.IX Subsection "get_inflator"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \f(CW$inflator\fR
.PP
Accepts the same arguments as "get_inflators", but only returns the
first inflator found.
.SS get_validators
.IX Subsection "get_validators"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \e@validators
.PP
Returns all validators from all fields.
.PP
Accepts both \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`type\*(C'\fR arguments to narrow the returned results.
.PP
.Vb 4
\&    $form\->get_validators({
\&        name => \*(Aqfoo\*(Aq,
\&        type => \*(AqCallback\*(Aq,
\&    });
.Ve
.SS get_validator
.IX Subsection "get_validator"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \f(CW$validator\fR
.PP
Accepts the same arguments as "get_validators", but only returns the
first validator found.
.SS get_transformers
.IX Subsection "get_transformers"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \e@transformers
.PP
Returns all transformers from all fields.
.PP
Accepts both \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`type\*(C'\fR arguments to narrow the returned results.
.PP
.Vb 4
\&    $form\->get_transformers({
\&        name => \*(Aqfoo\*(Aq,
\&        type => \*(AqCallback\*(Aq,
\&    });
.Ve
.SS get_transformer
.IX Subsection "get_transformer"
Arguments: [%options]
.PP
Arguments: [\e%options]
.PP
Return Value: \f(CW$transformer\fR
.PP
Accepts the same arguments as "get_transformers", but only returns the
first transformer found.
.SS clone
.IX Subsection "clone"
Returns a deep clone of the <$form> object.
.PP
Because of scoping issues, code references (such as in Callback constraints)
are copied instead of cloned.
.SH "ATTRIBUTE ACCESSORS"
.IX Header "ATTRIBUTE ACCESSORS"
For the basic method, e.g. \f(CW\*(C`/attributes\*(C'\fR:
.PP
Arguments: [%attributes]
.PP
Arguments: [\e%attributes]
.PP
Return Value: \f(CW$form\fR
.PP
As a special case, if no arguments are passed, the attributes hash-ref is
returned. This allows the following idioms.
.PP
.Vb 2
\&    # set a value
\&    $form\->attributes\->{id} = \*(Aqform\*(Aq;
\&
\&    # delete all attributes
\&    %{ $form\->attributes } = ();
.Ve
.PP
All methods documented as 'attribute accessors' also have the following
variants generated:
.PP
\&\f(CW*_xml\fR can be used as a setter, and ensures that its argument is not
XML-escaped in the rendered form.
.PP
\&\f(CW*_loc\fR can he used as a setter, and passes the arguments through
"localize".
.PP
\&\f(CW\*(C`add_*\*(C'\fR can be used to append a word to an attribute without overwriting
any already-existing value.
.PP
.Vb 4
\&    # Example
\&    $form\->attributes({ class => \*(Aqfancy\*(Aq });
\&    $form\->add_attributes({ class => \*(Aqpants\*(Aq });
\&    # class="fancy pants"
.Ve
.PP
\&\f(CW\*(C`add_*_xml\*(C'\fR, like \f(CW\*(C`add_*\*(C'\fR, but ensures it doesn't get XML-escaped.
.PP
\&\f(CW\*(C`add_*_loc\*(C'\fR, like \f(CW\*(C`add_*\*(C'\fR, but passing the arguments through "localize".
.PP
\&\f(CW\*(C`del_*\*(C'\fR can be used to remove a word from an attribute value.
.PP
.Vb 4
\&    # Example
\&    $form\->attributes({ class => \*(Aqfancy pants\*(Aq });
\&    $form\->del_attributes({ class => \*(Aqpants\*(Aq });
\&    # class="fancy"
.Ve
.PP
\&\f(CW\*(C`del_*_xml\*(C'\fR, like \f(CW\*(C`del_*\*(C'\fR, but ensures it doesn't get XML-escaped.
.PP
\&\f(CW\*(C`del_*_loc\*(C'\fR, like \f(CW\*(C`del_*\*(C'\fR, but passing the arguments through "localize".
.PP
Also, any attribute method-name which contains the word \f(CW\*(C`attributes\*(C'\fR also
has aliases created for all these variants, with the word \f(CW\*(C`attributes\*(C'\fR
replaced by \f(CW\*(C`attrs\*(C'\fR.
.PP
.Vb 2
\&    # For example, the attributes() method would have all these variant
\&    # methods available
\&
\&    $form\->attributes({ class => \*(Aqfancy\*(Aq });
\&    $form\->attributes_xml({ title => \*(Aq<b>fancy</b>\*(Aq });
\&    $form\->attributes_loc({ title => \*(Aqfancy\*(Aq });
\&    $form\->add_attributes({ class => \*(Aqfancy\*(Aq });
\&    $form\->add_attributes_xml({ title => \*(Aq<b>fancy</b>\*(Aq });
\&    $form\->add_attributes_loc({ title => \*(Aqfancy\*(Aq });
\&    $form\->del_attributes({ class => \*(Aqfancy\*(Aq });
\&    $form\->del_attributes_xml({ title => \*(Aq<b>fancy</b>\*(Aq });
\&    $form\->del_attributes_loc({ title => \*(Aqfancy\*(Aq });
\&
\&    # Because the method contains the word \*(Aqattributes\*(Aq, it also gets the
\&    # following short\-forms
\&
\&    $form\->attrs({ class => \*(Aqfancy\*(Aq });
\&    $form\->attrs_xml({ title => \*(Aq<b>fancy</b>\*(Aq });
\&    $form\->attrs_loc({ title => \*(Aqfancy\*(Aq });
\&    $form\->add_attrs({ class => \*(Aqfancy\*(Aq });
\&    $form\->add_attrs_xml({ title => \*(Aq<b>fancy</b>\*(Aq });
\&    $form\->add_attrs_loc({ title => \*(Aqfancy\*(Aq });
\&    $form\->del_attrs({ class => \*(Aqfancy\*(Aq });
\&    $form\->del_attrs_xml({ title => \*(Aq<b>fancy</b>\*(Aq });
\&    $form\->del_attrs_loc({ title => \*(Aqfancy\*(Aq });
.Ve
.SH "ATTRIBUTE SHORT-CUTS"
.IX Header "ATTRIBUTE SHORT-CUTS"
All methods documented as 'attribute short\-cuts' are short-cuts to directly
access individual attribute key/values.
.PP
.Vb 3
\&    # Example
\&    $form\->id( \*(Aqlogin\*(Aq );
\&    $id = $form\->id;
\&
\&    # is equivalent to:
\&    $form\->attributes({ id => \*(Aqlogin\*(Aq });
\&    $id = $form\->attributes\->{id};
.Ve
.PP
All attribute short-cuts also have a \f(CW*_xml\fR variant.
.PP
.Vb 2
\&    # Example
\&    $form\->id_xml( $xml );
\&
\&    # is equivalent to:
\&    $form\->attributes_xml({ id => $xml });
.Ve
.PP
All attribute short-cuts also have a \f(CW*_loc\fR variant.
.PP
.Vb 2
\&    # Example
\&    $form\->title_loc( $key );
\&
\&    # is equivalent to:
\&    $form\->attributes_loc({ title => $key });
.Ve
.SH "INHERITING ACCESSORS"
.IX Header "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.
.PP
All inherited accessors also have a \f(CW*_no_inherit\fR 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.
.PP
E.g., the "auto_id" has a variant named \f(CW\*(C`auto_id_no_inherit\*(C'\fR.
.SH "OUTPUT ACCESSORS"
.IX Header "OUTPUT ACCESSORS"
All methods documented as 'output accessors' also have \f(CW*_xml\fR and \f(CW*_loc\fR
variants.
.PP
The \f(CW*_xml\fR variant can be used as a setter, and ensures that its
argument is not XML-escaped in the rendered form.
.PP
The \f(CW*_loc\fR variant can be used as a setter, and passes the arguments
through "localize".
.PP
E.g., the label method has
variants named \f(CW\*(C`label_xml\*(C'\fR and \f(CW\*(C`label_loc\*(C'\fR.
.SH "BOOLEAN ATTRIBUTE ACCESSORS"
.IX Header "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.
.PP
.Vb 1
\&    # Example
\&
\&    $field\->autofocus(1);
\&    # equivalent to:
\&    $field\->attributes({ autofocus => \*(Aqautofocus\*(Aq });
\&
\&    $field\->autofocus(0);;
\&    # equivalent to:
\&    delete $field\->attributes\->{autofocus};
.Ve
.SH "ATTRIBUTE SUBSTITUTIONS"
.IX Header "ATTRIBUTE SUBSTITUTIONS"
Some attributes support character substitutions: the following substitutions
are possible:
.PP
.Vb 5
\&    %f # $form\->id
\&    %n # $field\->name
\&    %t # lc( $field\->type )
\&    %r # $block\->repeatable_count
\&    %s # $error\->stage
.Ve
.PP
These allow each field to have consistent attributes, while remaining unique.
.SH "DEPRECATION POLICY"
.IX Header "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.
.SH "RESTORING LEGACY HTML CLASSES"
.IX Header "RESTORING LEGACY HTML CLASSES"
\&\f(CW\*(C`v1.00\*(C'\fR 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.
.PP
To restore the previous behaviour, set the following options.
.PP
If you're using best practices, you'll only need to set
these once per-application in your app-wide config file.
.PP
.Vb 8
\&    \-\-\-
\&    auto_container_class: \*(Aq%t\*(Aq
\&    auto_container_label_class: \*(Aqlabel\*(Aq
\&    auto_container_comment_class: \*(Aqcomment\*(Aq
\&    auto_comment_class: \*(Aqcomment\*(Aq
\&    auto_container_error_class: \*(Aqerror\*(Aq
\&    auto_container_per_error_class: \*(Aqerror_%s_%t\*(Aq
\&    auto_error_class: \*(Aqerror_message error_%s_%t\*(Aq
.Ve
.SH "DEPRECATED METHODS"
.IX Header "DEPRECATED METHODS"
See "DEPRECATED METHODS" in HTML::FormFu::Role::Element::Field.
.SH "REMOVED METHODS"
.IX Header "REMOVED METHODS"
See also "REMOVED METHODS" in HTML::FormFu::Element.
.SS element_defaults
.IX Subsection "element_defaults"
Has been removed; see "default_args" instead.
.SS model_class
.IX Subsection "model_class"
Has been removed; use "default_model" instead.
.SS defaults_from_model
.IX Subsection "defaults_from_model"
Has been removed; use "default_values" in HTML::FormFu::Model instead.
.SS save_to_model
.IX Subsection "save_to_model"
Has been removed; use "update" in HTML::FormFu::Model instead.
.SH "BEST PRACTICES"
.IX Header "BEST PRACTICES"
It is advisable to keep application-wide (or global) settings in a single
config file, which should be loaded by each form.
.PP
See "load_config_file".
.SH COOKBOOK
.IX Header "COOKBOOK"
HTML::FormFu::Manual::Cookbook
.SS UNICODE
.IX Subsection "UNICODE"
HTML::FormFu::Manual::Unicode
.SH EXAMPLES
.IX Header "EXAMPLES"
.SS "vertically-aligned CSS"
.IX Subsection "vertically-aligned CSS"
The distribution directory \f(CW\*(C`examples/vertically\-aligned\*(C'\fR contains a form with
example CSS for a "vertically aligned" theme.
.PP
This can be viewed by opening the file \f(CW\*(C`vertically\-aligned.html\*(C'\fR in a
web-browser.
.PP
If you wish to experiment with making changes, the form is defined in file
\&\f(CW\*(C`vertically\-aligned.yml\*(C'\fR, and the HTML file can be updated with any changes
by running the following command (while in the distribution root directory).
.PP
.Vb 1
\&    perl examples/vertically\-aligned/vertically\-aligned.pl
.Ve
.PP
This uses the Template Toolkit file \f(CW\*(C`vertically\-aligned.tt\*(C'\fR,
and the CSS is defined in files \f(CW\*(C`vertically\-aligned.css\*(C'\fR and
\&\f(CW\*(C`vertically\-aligned\-ie.css\*(C'\fR.
.SH SUPPORT
.IX Header "SUPPORT"
Project Page:
.PP
<http://code.google.com/p/html\-formfu/>
.PP
Mailing list:
.PP
<http://lists.scsys.co.uk/cgi\-bin/mailman/listinfo/html\-formfu>
.PP
Mailing list archives:
.PP
<http://lists.scsys.co.uk/pipermail/html\-formfu/>
.PP
IRC:
.PP
\&\f(CW\*(C`irc.perl.org\*(C'\fR, channel \f(CW\*(C`#formfu\*(C'\fR
.PP
The HTML::Widget archives <http://lists.scsys.co.uk/pipermail/html\-widget/>
between January and May 2007 also contain discussion regarding HTML::FormFu.
.SH BUGS
.IX Header "BUGS"
Please submit bug reports to the Debian Bug Tracker. You can use
\&\fBreportbug\fR\|(1) to do so interactively. A list of reported bugs can be found
at <http://bugs.debian.org/libhtml\-formfu\-perl>.
.PP
For upstream bug reports look at
<https://github.com/FormFu/HTML\-FormFu/issues> (preferred) or
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML\-FormFu>.
.SH PATCHES
.IX Header "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 \f(CW\*(C`svn diff > patchfile\*(C'\fR); mention which svn version it's against.
Mailing list messages are limited to 256KB, so gzip the patch if necessary.
.SH "GITHUB REPOSITORY"
.IX Header "GITHUB REPOSITORY"
This module's sourcecode is maintained in a git repository at
<git://github.com/FormFu/HTML\-FormFu.git>
.PP
The project page is <https://github.com/FormFu/HTML\-FormFu>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
HTML::FormFu::Imager
.PP
Catalyst::Controller::HTML::FormFu
.PP
HTML::FormFu::Model::DBIC
.SH CONTRIBUTORS
.IX Header "CONTRIBUTORS"
Brian Cassidy
.PP
Ozum Eldogan
.PP
Ruben Fonseca
.PP
Ronald Kimball
.PP
Daisuke Maki
.PP
Andreas Marienborg
.PP
Mario Minati
.PP
Steve Nolte
.PP
Moritz Onken
.PP
Doug Orleans
.PP
Matthias Dietrich
.PP
Dean Hamstead
.PP
Karen Etheridge
.PP
Nigel Metheringham
.PP
Based on the original source code of HTML::Widget, by Sebastian Riedel,
\&\f(CW\*(C`sri@oook.de\*(C'\fR.
.SH AUTHOR
.IX Header "AUTHOR"
Carl Franks <cpan@fireartist.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2018 by Carl Franks.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.