NAME¶
HTML::FormFu - HTML Form Creation, Rendering and Validation Framework
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.
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.
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');
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.
Arguments: $string
If you don't want your error message to be XML-escaped, use the
"form_error_message_xml" method instead.
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 (or derived from 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'
To have defaults only be applied to the specific named type, rather than
searching through derived types, append the type-name with "+".
For example, to have the following attributes only be applied to a
"Block" element, rather than any element that inherits from
"Block", such as "Multi":
default_args:
elements:
+Block:
attributes:
class: block
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 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".
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".
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 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¶
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
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.
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 each form field 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
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_label¶
Arguments: [$string]
If set, then each form field will be given an auto-generated label, 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
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_error_class¶
Arguments: [$string]
If set, then each form error 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'
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_error_message¶
Arguments: [$string]
If set, then each form field will be given an auto-generated message, 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, %t will be replaced by
lc( $field->type ), %s will be replaced by $error->stage.
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'
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_constraint_class¶
Arguments: [$string]
If set, then each form field 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
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_inflator_class¶
Arguments: [$string]
If set, then each form field 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
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_validator_class¶
Arguments: [$string]
If set, then each form field 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
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.
Arguments: [$string]
If set, then each form field 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
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.
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.
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¶
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
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.
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: "<TMPL_VAR form>", Petal: "<form
tal:replace="form"></form>" or Template::Magic:
"<!-- {form} -->".
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.
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.
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',
});
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.
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.
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".
SUPPORT¶
Website:
<
http://www.formfu.org>
Project Page:
http://code.google.com/p/html-formfu/
<
http://code.google.com/p/html-formfu/>
Mailing list:
http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/html-formfu
<
http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/html-formfu>
Mailing list archives:
http://lists.scsys.co.uk/pipermail/html-formfu/
<
http://lists.scsys.co.uk/pipermail/html-formfu/>
IRC:
"irc.perl.org", channel "#formfu"
The HTML::Widget archives
http://lists.scsys.co.uk/pipermail/html-widget/
<
http://lists.scsys.co.uk/pipermail/html-widget/> between January and
May 2007 also contain discussion regarding HTML::FormFu.
BUGS¶
Please submit bug reports to the Debian Bug Tracker. You can use
reportbug(1) to do so interactively. A list of reported bugs can be
found at
http://bugs.debian.org/libhtml-formfu-perl
<
http://bugs.debian.org/libhtml-formfu-perl>.
For upstream bug reports look at
http://code.google.com/p/html-formfu/issues/list
<
http://code.google.com/p/html-formfu/issues/list> (preferred) or
http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML-FormFu
<
http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML-FormFu>.
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.
GITHUB REPOSITORY¶
This module's sourcecode is maintained in a git repository at
git://github.com/fireartist/HTML-FormFu.git
<
git://github.com/fireartist/HTML-FormFu.git>
The project page is
https://github.com/fireartist/HTML-FormFu
<
https://github.com/fireartist/HTML-FormFu>
SEE ALSO¶
HTML::FormFu::Imager
Catalyst::Controller::HTML::FormFu
HTML::FormFu::Model::DBIC
AUTHORS¶
Carl Franks
CONTRIBUTORS¶
Brian Cassidy
Ozum Eldogan
Ruben Fonseca
Ronald Kimball
Daisuke Maki
Andreas Marienborg
Mario Minati
Steve Nolte
Moritz Onken
Doug Orleans
Matthias Dietrich
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.
PERL GAME¶
Play the MMO written in perl: <
http://www.lacunaexpanse.com>!