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

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

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

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 programmatically-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: .

As of HTML::FormFu v1.00, TT is no longer listed a required prerequisite - so you'll need to install it manually if you wish 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.

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, [email protected].

AUTHOR

Carl Franks <[email protected]>

COPYRIGHT AND LICENSE

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

Name		Name	Last commit message	Last commit date
Latest commit History 1,339 Commits
.github/workflows		.github/workflows
benchmarks		benchmarks
bin		bin
examples		examples
lib/HTML		lib/HTML
share/templates/tt/xhtml		share/templates/tt/xhtml
t		t
xt		xt
.gitignore		.gitignore
.mailmap		.mailmap
.perltidyrc		.perltidyrc
.travis.yml		.travis.yml
Changes		Changes
MANIFEST.SKIP		MANIFEST.SKIP
README.pod		README.pod
dist.ini		dist.ini

FormFu/HTML-FormFu

Folders and files

Latest commit

History

Repository files navigation

SYNOPSIS

DESCRIPTION

BUILDING A FORM

new

load_config_file

config_callback

populate

default_values

config_file_path

indicator

auto_fieldset

form_error_message

force_error_message

default_args

Pseudo types

Alternatives

Match ancestor

Don't match ancestor

Order

Clashes

Strictness

javascript

javascript_src

stash

elements

element

deflators

deflator

insert_before

insert_after

remove_element

FORM LOGIC AND VALIDATION

filters

filter

constraints

constraint

inflators

inflator

validators

validator

transformers

transformer

CHANGING DEFAULT BEHAVIOUR

render_processed_value

force_errors

params_ignore_underscore

FORM ATTRIBUTES

attributes

id

action

enctype

method

title

CSS CLASSES

form_error_message_class

LOCALIZATION

languages

localize_class

localize

loc

locale

PROCESSING A FORM

query

query_type

process

SUBMITTED FORM VALUES AND ERRORS

submitted

submitted_and_valid

params

param_value

param_array

param_list

param

valid

has_errors