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.

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.

load_config_file

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.

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

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.

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.

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".

Alternatives

# 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:

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.

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:

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:

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

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

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

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

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

filters

filter

Arguments: $type

Arguments: \%options

Return Value: $filter

Arguments: \@arrayref_of_types_or_options

Return Value: @filters

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

CHANGING DEFAULT BEHAVIOUR

render_processed_value

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

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

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

Default Value: false

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

force_errors

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.

locale

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.

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.

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.

MODEL / DATABASE INTERACTION

default_model

model

Arguments: [$model_name]

Return Value: $model

model_config

Arguments: \%config

MODIFYING A SUBMITTED FORM

add_valid

Arguments: $name, $value

Return Value: $value

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

PLUGIN SYSTEM

ADVANCED CUSTOMISATION

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

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

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

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

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.

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.

tt_args

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

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.

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.

ATTRIBUTE SUBSTITUTIONS

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.

COOKBOOK

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.

BUGS

PATCHES

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