Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/leto/html-formfu

Release history of HTML-FormFu
https://github.com/leto/html-formfu

Last synced: about 2 months ago
JSON representation

Release history of HTML-FormFu

Host: GitHub
URL: https://github.com/leto/html-formfu
Owner: leto
Created: 2011-03-16T18:53:50.000Z (almost 14 years ago)
Default Branch: master
Last Pushed: 2011-03-16T19:50:31.000Z (almost 14 years ago)
Last Synced: 2024-06-11T18:57:30.581Z (7 months ago)
Language: Perl
Homepage: http://search.cpan.org/dist/HTML-FormFu/
Size: 911 KB
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README
- Changelog: Changes

Awesome Lists containing this project

README

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

BETA SOFTWARE
There may be API changes required before the 1.0 release. Any
incompatible changes will first be discussed on the mailing list. See
"DEPRECATION POLICY" for further details.

Work is still needed on the documentation, if you come across any errors
or find something confusing, please give feedback via the mailing list.

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 strict;
use base '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

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

2 elements with an "auto_fieldset".

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

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

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 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 I18N
file.

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 listed type which is 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'

To take it even further, you can even 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'

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
Arguments: [$javascript]

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

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 ELEMENTS" in
HTML::FormFu::Element for a list of core elements.

If you want to load an element from a namespace other than
"HTML::FormFu::Element::", you can use a fully qualified package-name by
prefixing it with "+".

---
elements:
- type: +MyApp::CustomElement
name: foo

If a "type" is not provided in the "\%options", the default "Text" will
be used.

"element" is an alias for "elements".

deflators
deflator
Arguments: $type

Arguments: \%options

Return Value: $deflator

Arguments: \@arrayref_of_types_or_options

Return Value: @deflators

A deflator may be associated with any form field, and allows you to
provide <$field->default> with a value which may be an object.

If an object doesn't stringify to a suitable value for display, the
deflator can ensure that the form field receives a suitable string value
instead.

See "CORE DEFLATORS" in HTML::FormFu::Deflator for a list of core
deflators.

If a "name" attribute isn't provided, a new deflator is created for and
added to every field on the form.

If you want to load a deflator in a namespace other than
"HTML::FormFu::Deflator::", you can use a fully qualified package-name
by prefixing it with "+".

"deflator" is an alias for "deflators".

insert_before
Arguments: $new_element, $existing_element

Return Value: $new_element

The 1st argument must be the element you want added, the 2nd argument
must be the existing element that the new element should be placed
before.

my $new = $form->element(\%specs);

my $position = $form->get_element({ type => $type, name => $name });

$form->insert_before( $new, $position );

In the first line of the above example, the $new element is initially
added to the end of the form. However, the "insert_before" method
reparents the $new element, so it will no longer be on the end of the
form. Because of this, if you try to copy an element from one form to
another, it will 'steal' the element, instead of copying it. In this
case, you must use "clone":

my $new = $form1->get_element({ type => $type1, name => $name1 })
->clone;

my $position = $form2->get_element({ type => $type2, name => $name2 });

$form2->insert_before( $new, $position );

insert_after
Arguments: $new_element, $existing_element

Return Value: $new_element

The 1st argument must be the element you want added, the 2nd argument
must be the existing element that the new element should be placed
after.

my $new = $form->element(\%specs);

my $position = $form->get_element({ type => $type, name => $name });

$form->insert_after( $new, $position );

In the first line of the above example, the $new element is initially
added to the end of the form. However, the "insert_after" method
reparents the $new element, so it will no longer be on the end of the
form. Because of this, if you try to copy an element from one form to
another, it will 'steal' the element, instead of copying it. In this
case, you must use "clone":

my $new = $form1->get_element({ type => $type1, name => $name1 })
->clone;

my $position = $form2->get_element({ type => $type2, name => $name2 });

$form2->insert_after( $new, $position );

remove_element
Arguments: $element

Return Value: $element

Removes the $element from the form or block's array of children.

$form->remove_element( $element );

The orphaned element cannot be usefully used for anything until it is
re-attached to a form or block with "insert_before" or "insert_after".

FORM LOGIC AND VALIDATION
HTML::FormFu provides several stages for what is traditionally described
as *validation*. These are:

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

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

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

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

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

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

filters
filter
Arguments: $type

Arguments: \%options

Return Value: $filter

Arguments: \@arrayref_of_types_or_options

Return Value: @filters

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

See "CORE FILTERS" in HTML::FormFu::Filter for a list of core filters.

If you want to load a filter in a namespace other than
"HTML::FormFu::Filter::", you can use a fully qualified package-name by
prefixing it with "+".

"filter" is an alias for "filters".

constraints
constraint
Arguments: $type

Arguments: \%options

Return Value: $constraint

Arguments: \@arrayref_of_types_or_options

Return Value: @constraints

See "CORE CONSTRAINTS" in HTML::FormFu::Constraint for a list of core
constraints.

If a "name" attribute isn't provided, a new constraint is created for
and added to every field on the form.

If you want to load a constraint in a namespace other than
"HTML::FormFu::Constraint::", you can use a fully qualified package-name
by prefixing it with "+".

"constraint" is an alias for "constraints".

inflators
inflator
Arguments: $type

Arguments: \%options

Return Value: $inflator

Arguments: \@arrayref_of_types_or_options

Return Value: @inflators

See "CORE INFLATORS" in HTML::FormFu::Inflator for a list of core
inflators.

If a "name" attribute isn't provided, a new inflator is created for and
added to every field on the form.

If you want to load an inflator in a namespace other than
"HTML::FormFu::Inflator::", you can use a fully qualified package-name
by prefixing it with "+".

"inflator" is an alias for "inflators".

validators
validator
Arguments: $type

Arguments: \%options

Return Value: $validator

Arguments: \@arrayref_of_types_or_options

Return Value: @validators

See "CORE VALIDATORS" in HTML::FormFu::Validator for a list of core
validators.

If a "name" attribute isn't provided, a new validator is created for and
added to every field on the form.

If you want to load a validator in a namespace other than
"HTML::FormFu::Validator::", you can use a fully qualified package-name
by prefixing it with "+".

"validator" is an alias for "validators".

transformers
transformer
Arguments: $type

Arguments: \%options

Return Value: $transformer

Arguments: \@arrayref_of_types_or_options

Return Value: @transformers

See "CORE TRANSFORMERS" in HTML::FormFu::Transformer for a list of core
transformers.

If a "name" attribute isn't provided, a new transformer is created for
and added to every field on the form.

If you want to load a transformer in a namespace other than
"HTML::FormFu::Transformer::", you can use a fully qualified
package-name by prefixing it with "+".

"transformer" is an alias for "transformers".

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

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

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

Default Value: false

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.

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
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", 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 preceding space
character. This is primarily to allow the easy addition of new names to
the class attribute.

$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", 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", 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" keys.

id
Arguments: [$id]

Return Value: $id

Get or set the form's DOM id.

Default Value: none

action
Arguments: [$uri]

Return Value: $uri

Get or set the action associated with the form. The default is no
action, which causes most browsers to submit to the current URI.

Default Value: ""

enctype
Arguments: [$enctype]

Return Value: $enctype

Get or set the encoding type of the form. Valid values are
"application/x-www-form-urlencoded" and "multipart/form-data".

If the form contains a File element, the enctype is automatically set to
"multipart/form-data".

method
Arguments: [$method]

Return Value: $method

Get or set the method used to submit the form. Can be set to either
"post" or "get".

Default Value: "post"

CSS CLASSES
auto_id
Arguments: [$string]

If set, then all form fields will be given an auto-generated id
attribute, if it doesn't have one already.

The following character substitution will be performed: %f will be
replaced by $form->id, %n will be replaced by $field->name, %r will be
replaced by $block->repeatable_count.

Default Value: not defined

auto_label
Arguments: [$string]

If set, then all form fields will be given an auto-generated name, if it
doesn't have one already.

The following character substitution will be performed: %f will be
replaced by $form->id, %n will be replaced by $field->name.

The generated string will be passed to "localize" to create the label.

Default Value: not defined

auto_error_class
Arguments: [$string]

If set, then all form errors will be given an auto-generated class-name.

The following character substitution will be performed: %f will be
replaced by $form->id, %n will be replaced by $field->name, %t will be
replaced by lc( $field->type ), %s will be replaced by $error->stage.

Default Value: 'error_%s_%t'

auto_error_message
Arguments: [$string]

If set, then all form fields will be given an auto-generated message, if
it doesn't have one already.

The generated string will be passed to "localize" to create the message.

For example, a Required constraint will return the string
"form_constraint_required". Under the default localization behaviour,
the appropriate message for "form_constraint_required" will be used from
the default I18N package.

Default Value: 'form_%s_%t'

auto_constraint_class
Arguments: [$string]

If set, then all form fields will be given an auto-generated class-name
for each associated constraint.

The following character substitution will be performed: %f will be
replaced by $form->id, %n will be replaced by $field->name, %t will be
replaced by lc( $field->type ).

Default Value: not defined

auto_inflator_class
Arguments: [$string]

If set, then all form fields will be given an auto-generated class-name
for each associated inflator.

The following character substitution will be performed: %f will be
replaced by $form->id, %n will be replaced by $field->name, %t will be
replaced by lc( $field->type ).

Default Value: not defined

auto_validator_class
Arguments: [$string]

If set, then all form fields will be given an auto-generated class-name
for each associated validator.

The following character substitution will be performed: %f will be
replaced by $form->id, %n will be replaced by $field->name, %t will be
replaced by lc( $field->type ).

Default Value: not defined

auto_transformer_class
Arguments: [$string]

If set, then all form fields will be given an auto-generated class-name
for each associated validator.

The following character substitution will be performed: %f will be
replaced by $form->id, %n will be replaced by $field->name, %t will be
replaced by lc( $field->type ).

Default Value: not defined

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.

PROCESSING A FORM
query
Arguments: [$query_object]

Arguments: \%params

Provide a CGI compatible query object or a hash-ref of submitted
names/values. Alternatively, the query object can be passed directly to
the "process" object.

query_type
Arguments: [$query_type]

Set which module is being used to provide the "query".

The Catalyst::Controller::HTML::FormFu automatically sets this to
"Catalyst".

Valid values are "CGI", "Catalyst" and "CGI::Simple".

Default Value: 'CGI'

process
Arguments: [$query_object]

Arguments: [\%params]

Process the provided query object or input values. "process" must be
called before calling any of the methods listed under "SUBMITTED FORM
VALUES AND ERRORS" and "MODIFYING A SUBMITTED FORM".

"process" must also be called at least once before printing the form or
calling "render" or "render_data".

Note to users of Catalyst::Controller::HTML::FormFu: Because "process"
is automatically called for you by the Catalyst controller; if you make
any modifications to the form within your action method, such as adding
or changing elements, adding constraints, etc; you must call "process"
again yourself before using "submitted_and_valid", any of the methods
listed under "SUBMITTED FORM VALUES AND ERRORS" or "MODIFYING A
SUBMITTED FORM", or rendering the form.

SUBMITTED FORM VALUES AND ERRORS
submitted
Returns true if the form has been submitted. See "indicator" for details
on how this is computed.

submitted_and_valid
Shorthand for "$form->submitted && !$form->has_errors"

params
Return Value: \%params

Returns a hash-ref of all valid input for which there were no errors.

param_value
Arguments: $field_name

A more reliable, recommended version of "param". Guaranteed to always
return a single value, regardless of whether it's called in list context
or not. If multiple values were submitted, this only returns the first
value. If the value is invalid or the form was not submitted, it returns
"undef". This makes it suitable for use in list context, where a single
value is required.

$db->update({
name => $form->param_value('name'),
address => $form->param_value('address),
});

param_array
Arguments: $field_name

Guaranteed to always return an array-ref of values, regardless of
context and regardless of whether multiple values were submitted or not.
If the value is invalid or the form was not submitted, it returns an
empty array-ref.

param_list
Arguments: $field_name

Guaranteed to always return a list of values, regardless of context. If
the value is invalid or the form was not submitted, it returns an empty
list.

param
Arguments: [$field_name]

Return Value: $input_value

Return Value: @valid_names

No longer recommended for use, as its behaviour is hard to predict. Use
param_value, param_array or param_list instead.

A (readonly) method similar to that of CGI's.

If a field name is given, in list-context returns any valid values
submitted for that field, and in scalar-context returns only the first
of any valid values submitted for that field.

If no argument is given, returns a list of all valid input field names
without errors.

Passing more than 1 argument is a fatal error.

valid
Arguments: [$field_name]

Return Value: @valid_names

Return Value: $bool

If a field name if given, returns "true" if that field had no errors and
"false" if there were errors.

If no argument is given, returns a list of all valid input field names
without errors.

has_errors
Arguments: [$field_name]

Return Value: @names

Return Value: $bool

If a field name if given, returns "true" if that field had errors and
"false" if there were no errors.

If no argument is given, returns a list of all input field names with
errors.

get_errors
Arguments: [%options]

Arguments: [\%options]

Return Value: \@errors

Returns an array-ref of exception objects from all fields in the form.

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

$form->get_errors({
name => 'foo',
type => 'Regex',
stage => 'constraint'
});

get_error
Arguments: [%options]

Arguments: [\%options]

Return Value: $error

Accepts the same arguments as "get_errors", but only returns the first
error found.

MODEL / DATABASE INTERACTION
See HTML::FormFu::Model for further details and available models.

default_model
Arguments: $model_name

Default Value: 'DBIC'

model
Arguments: [$model_name]

Return Value: $model

model_config
Arguments: \%config

MODIFYING A SUBMITTED FORM
add_valid
Arguments: $name, $value

Return Value: $value

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

clear_errors
Deletes all errors from a submitted form.

RENDERING A FORM
render
Return Value: $string

You must call "process" once after building the form, and before calling
"render".

start
Return Value: $string

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

Implicitly uses the "tt" "render_method".

end
Return Value: $string

Returns the form end tag.

Implicitly uses the "tt" "render_method".

hidden_fields
Return Value: $string

Returns all hidden form fields.

PLUGIN SYSTEM
"HTML::FormFu" provides a plugin-system that allows plugins to be easily
added to a form or element, to change the default behaviour or output.

See HTML::FormFu::Plugin for details.

ADVANCED CUSTOMISATION
By default, formfu renders "XHTML 1.0 Strict" compliant markup, with as
little extra markup as possible, but with sufficient CSS class names to
allow for a wide-range of output styles to be generated by changing only
the CSS.

If you wish to customise the markup, you'll need to tell 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: "", Petal: "" or Template::Magic: "".

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

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

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.

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.

DEPRECATED METHODS
element_defaults
Is deprecated and provided only for backwards compatability. Will be
removed at some point in the future.

See "default_args" instead.

model_class
Is deprecated and provided only for backwards compatability. Will be
removed at some point in the future.

Use "default_model" instead.

defaults_from_model
Is deprecated and provided only for backwards compatability. Will be
removed at some point in the future.

Use "default_values" in HTML::FormFu::Model instead.

$form->model->default_values( $object, \%config )

save_to_model
Is deprecated and provided only for backwards compatability. Will be
removed at some point in the future.

Use "update" in HTML::FormFu::Model instead.

$form->model->update( $object, \%config )

DEPRECATION POLICY
We try our best to not make incompatable 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.

BEST PRACTICES
It is advisable to keep application-wide (or global) settings in a
single config file, which should be loaded by each form.

See "load_config_file".

COOKBOOK
HTML::FormFu::Manual::Cookbook

UNICODE
HTML::FormFu::Manual::Unicode

EXAMPLES
vertically-aligned CSS
The distribution directory "examples/vertically-aligned" contains a form
with example CSS for a "vertically aligned" theme.

This can be viewed by opening the file "vertically-aligned.html" in a
web-browser.

If you wish to experiment with making changes, the form is defined in
file "vertically-aligned.yml", and the HTML file can be updated with any
changes by running the following command (while in the distribution root
directory).

perl examples/vertically-aligned/vertically-aligned.pl

This uses the Template Toolkit file "vertically-aligned.tt", and the CSS
is defined in files "vertically-aligned.css" and
"vertically-aligned-ie.css".

SUPPORT
Website:

Project Page:

Mailing list:

Mailing list archives:

IRC:

"irc.perl.org", channel "#formfu"

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

BUGS
Please submit bugs / feature requests to
(preferred) or
.

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.

SUBVERSION REPOSITORY
The publicly viewable subversion code repository is at
.

If you wish to contribute, you'll need a google account. Then just ask
on the mailing list for commit access, giving the email address your
account uses.

If you wish to contribute but for some reason really don't want to sign
up for a google 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: