Why not adopt me?

This distribution is up for adoption! If you're interested then please contact the PAUSE module admins via email.

NAME

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

BETA SOFTWARE

Please note that this is beta software.

There may be API changes required before the 1.0 release. Any incompatible changes will first be discussed on the mailing list.

Much work is needed on documentation, and contributions are welcome. This file is quite extensively documented, but may contain errors due to more recent code changes. Some pm files may not be documented at all yet, so please refer to the test suite, the code, or questions are welcome on the mailing list.

SYNOPSIS

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 );
}

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

---
action: /login
indicator: user
auto_fieldset: 1
elements:
  - type: text
    name: user
    constraints: 
      - Required
  - type: password
    name: pass
    constraints:
      - Required
  - type: submit

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, as so allow common settings to be kept in a single config file which may be loaded by any form.

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"

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.

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 it's 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">
  <span class="text">
    <input name="foo" type="text" />
  </span>
  <span class="text">
    <input name="bar" type="text" />
  </span>
</form>

2 elements with an "auto_fieldset".

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

<form action="" method="post">
  <fieldset>
    <span class="text">
      <input name="foo" type="text" />
    </span>
    <span class="text">
      <input name="bar" type="text" />
    </span>
  </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">
    <span class="text">
      <input name="foo" type="text" />
    </span>
    <span class="text">
      <input name="bar" type="text" />
    </span>
  </fieldset>
  <fieldset>
    <span class="text">
      <input name="baz" type="text" />
    </span>
  </fieldset>
</form>

Because of this behaviour, if you want nested fieldsets you will have to add each nested fieldset directly to it's 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 change the markup used to display the message, edit the form_error_message template file.

form_error_message_xml

Arguments: $string

If you don't want your error message to be XML-escaped, use the "form_error_message_xml" method instead.

form_error_message_loc

Arguments: $localization_key

For ease of use, if you'd like to use the provided localized error message, set "form_error_message_loc" to the value form_error_message.

You can, of course, set "form_error_message_loc" to any key in your L10N file.

force_error_message

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

element_defaults

Arguments: \%defaults

Set defaults which will be added to every element of that type which is added to the form.

For example, to make every text element automatically have a size of 10, and make every textarea element automatically get a class-name of bigbox:

element_defaults:
  text:
    size: 10
  textarea:
    add_attributes:
      class: bigbox

javascript

Arguments: [$javascript]

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

stash

Arguments: [\%private_stash]

Provides a hash-ref in which you can store any data you might want to associate with the form. This data will not be used by HTML::FormFu at all.

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

FORM LOGIC AND VALIDATION

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

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

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

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

Constraints are intended for low-level validation of values, such as "is this 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 allow for a more complex validation than Constraints. Validators can be sure that all values have successfully passed all Constraints and have been successfully passed through all Inflators. It is expected that most Validators will be application-specific, and so each will be implemented as a seperate class written by the HTML::FormFu user.

filters

filter

Arguments: $type

attributes

attrs

Arguments: [%attributes]

Arguments: [\%attributes]

Return Value: $form

Accepts either a list of key/value pairs, or a hash-ref.

---
attributes:
  id: form
  class: fancy_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 } = ();

"attrs" is an alias for "attributes".

attributes_xml

attrs_xml

Provides the same functionality as "attributes"" in ", but values won't be XML-escaped.

"attrs_xml" is an alias for "attributes_xml".

add_attributes

add_attrs

Arguments: [%attributes]

Arguments: [\%attributes]

Return Value: $form

Accepts either a list of key/value pairs, or a hash-ref.

$form->add_attributes( $key => $value );
$form->add_attributes( { $key => $value } );

All values are appended to existing values, with a preceeding space character. This is primarily to allow the easy addition of new class names.

$form->attributes({ class => 'foo' });

$form->add_attributes({ class => 'bar' });

# class is now 'foo bar'

"add_attrs" is an alias for "add_attributes".

add_attributes_xml

add_attrs_xml

Provides the same functionality as "add_attributes"" in ", but values won't be XML-escaped.

"add_attrs_xml" is an alias for "add_attributes_xml".

del_attributes

del_attrs

Arguments: [%attributes]

Arguments: [\%attributes]

Return Value: $form

Accepts either a list of key/value pairs, or a hash-ref.

$form->del_attributes( $key => $value );
$form->del_attributes( { $key => $value } );

All values are removed from the attribute value.

$form->attributes({ class => 'foo bar' });

$form->del_attributes({ class => 'bar' });

# class is now 'foo'

"del_attrs" is an alias for "del_attributes".

del_attributes_xml

del_attrs_xml

Provides the same functionality as "del_attributes"" in ", but values won't be XML-escaped.

"del_attrs_xml" is an alias for "del_attributes_xml".

The following methods are shortcuts for accessing "attributes"" in " keys.

id

Arguments: [$id]

Return Value: $id

Get or set the form's DOM id.

Default Value: none

action

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.

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. This must be called before calling any of the methods listed under "SUBMITTED FORM VALUES AND ERRORS" and "MODIFYING A SUBMITTED FORM".

It's not necessary to call "process" before printing the form or calling "render".

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

Arguments: [$field_name]

Return Value: $input_value

Return Value: @valid_names

A (readonly) CGI compatible method.

If a field name if 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.

MODIFYING A SUBMITTED FORM

add_valid

Arguments: $name, $value

Return Value: $value

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

clear_errors

Deletes all errors from a submitted form.

RENDERING A FORM

render

Return Value: $render_object

Returns a $render object which can either be printed, or used for more advanced custom rendering.

Using a $form object in string context (for example, printing it) automatically calls "render".

The default class of the returned render object is HTML::FormFu::Render::Form.

start_form

Return Value: $string

Convenience method for returning "start_form" in HTML::FormFu::Render::Form.

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

Equivalent to:

$form->render->start_form;

end_form

Return Value: $string

Convenience method for returning "end_form" in HTML::FormFu::Render::Form.

Returns the form end tag.

Equivalent to:

$form->render->end_form;

hidden_fields

Return Value: $string

Returns all hidden form fields.

ADVANCED CUSTOMISATION

filename

Change the template filename used for the form.

Default Value: "form"

render_class

Set the classname used to create a form render object. If set, the values of "render_class_prefix" and "render_class_suffix" are ignored.

Default Value: none

render_class_prefix

Set the prefix used to generate the classname of the form render object and all Element render objects.

Default Value: "HTML::FormFu::Render"

render_class_suffix

Set the suffix used to generate the classname of the form render object.

Default Value: "Form"

render_class_args

Arguments: [\%constructor_arguments]

Accepts a hash-ref of arguments passed to the render object constructor for the form and all elements.

The default render class (HTML::FormFu::Render::Base) passes these arguments to the TT constructor.

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

The default value of INCLUDE_PATH is root. This should generally be overridden to point to the location of the HTML::FormFu template files on your local system.

render_method

Arguments: [$method_name]

The method named called by "output" in HTML::FormFu::Render::base.

Default Value: 'xhtml'

INTROSPECTION

get_elements

Arguments: [%options]

Arguments: [\%options]

Return Value: \@elements

Returns all top-level elements in the form (not recursive).

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

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

See "get_all_elements" for a recursive version.

get_element

Arguments: [%options]

Arguments: [\%options]

Return Value: $element

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

get_all_elements

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',
});

get_field

Arguments: [%options]

Arguments: [\%options]

Return Value: $element

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

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.

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

FREQUENTLY ASKED QUESTIONS (FAQ)

It's too slow!

Are you using Catalyst::Plugin::StackTrace? This is known to cause performance problems, and we advise disabling it.

How do I add an onSubmit handler to the form?

---
attributes_xml: { onsubmit: $javascript }

See "attributes" in HTML::FormFu.

How do I add an onChange handler to a form field?

---
elements:
  - type: text
    attributes_xml: { onchange: $javascript }

See "attributes" in HTML::FormFu::Element.

Element X does not have an accessor for Y!

You can add any arbitrary HTML attributes with "attributes" in HTML::FormFu::Element.

How can I add a HTML tag which isn't included?

You can use the HTML::FormFu::Element::Block element, and set the tag to the tag type you want.

---
elements:
  - type: block
    tag: span

How do I check if a textfield contains a URI in a proper format?

Use HTML::FormFu::Constraint::Regex:

---
elements:
    - type: text
      name: uri
      constraint:
        - type: Regex
          common: [ URI, HTTP, { '-scheme': 'ftp|https?' ]

SUPPORT

Project Page:

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

Mailing list:

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

Mailing list archives:

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

The HTML::Widget archives between January and May 2007 also contain discussion regarding HTML::FormFu.

BUGS

Please submit bugs / feature requests to http://code.google.com/p/html-formfu/issues/list (preferred) or http://rt.perl.org.

SUBVERSION REPOSITORY

The publicly viewable subversion code repository is at http://html-formfu.googlecode.com/svn/trunk/HTML-FormFu.

If you wish to contribute, you'll need a GMAIL email address. Then just ask on the mailing list for commit access.

If you wish to contribute but for some reason really don't want to sign up for a GMAIL account, please post patches to the mailing list (although you'll have to wait for someone to commit them).

If you have commit permissions, use the HTTPS repository url: https://html-formfu.googlecode.com/svn/trunk/HTML-FormFu

AUTHORS

Carl Franks

CONTRIBUTORS

Brian Cassidy

Daisuke Maki

Andreas Marienborg

Mario Minati

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

LICENSE

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

To install HTML::FormFu, copy and paste the appropriate command in to your terminal.

cpanm

cpanm HTML::FormFu

CPAN shell

perl -MCPAN -e shell
install HTML::FormFu

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)