HTML::FormFu::Manual::UserbContributed Perl DHTML::FormFu::Manual::Cookbook(3)NAMEHTML::FormFu::Manual::Cookbook - Cooking with HTML::FormFu
DESCRIPTION
Miscellaneous useful recipes for use with HTML::FormFu
GETTING STARTED
Some useful info for beginners.
Default search paths for config files
The current working directory ("cwd") (see "load_config_file" in
HTML::FormFu).
If you're using the "FormConfig" action attribute from
Catalyst::Controller::HTML::FormFu, forms should be saved in
"root/forms". See "SYNOPSIS" in Catalyst::Controller::HTML::FormFu and
"config_file_path" in Catalyst::Controller::HTML::FormFu for further
details.
YAML
Most examples given in the HTML::FormFu documentation use YAML syntax.
You can use any configuration file type supported by Config::Any, but
this author's preferred format is YAML.
A form can be populated by a config file by calling "load_config_file"
in HTML::FormFu with the filename as an argument. The config file is
converted to a perl data-structure, and then passed to "populate" in
HTML::FormFu.
The config file must contain a hash-ref, with the keys corresponding to
form method-names, and the values being the method arguments. For
example, the following are equivalent:
---
auto_fieldset: 1
elements:
- name: foo
- name: bar
# the above YAML is equivalent to the following perl code
$form->auto_fieldset(1);
$form->elements([
{ name => 'foo' },
{ name => 'bar' },
]);
When writing your config file, remember that perl hashes are unordered
and cannot have multiple keys with the same name.
See "load_config_file" in HTML::FormFu and "populate" in HTML::FormFu
for more details.
See <http://www.yaml.org/spec/> for the YAML specification.
BUILDING A FORM
Quick single-file prototypes
You can run the following script to quickly view a form's markup -
replace the contents of the "__DATA__" section with your own YAML
config.
#!/usr/bin/perl
use strict;
use warnings;
use HTML::FormFu;
use YAML::XS qw( Load );
my $form = HTML::FormFu->new;
my $yaml = do { local $/; <DATA> };
my $data = Load($yaml);
$form->populate($data);
print $form;
__DATA__
---
auto_fieldset: 1
elements:
- type: Text
name: foo
Unsupported HTML tags
You can use the HTML::FormFu::Element::Block element, and set the tag
to create any arbitrary pair of tags.
---
elements:
- type: Block
tag: span
content_xml: "<b>Hi!</b>"
You can use "content" in HTML::FormFu::Element::Block, "content_xml" in
HTML::FormFu::Element::Block or "content_loc" in
HTML::FormFu::Element::Block to add any content you wish, or use
"element" in HTML::FormFu::Element::Block to add elements.
Application-wide default values
You can automatically set defaults using "default_args" in
HTML::FormFu, and if you set this in a Catalyst application config
file, it'll take effect throughout your entire application, for
example:
myapp.yml
---
'Controller::HTML::FormFu':
constructor:
default_args:
elements:
Checkbox:
reverse_multi: 1
Radio:
reverse_multi: 1
MODIFYING A FORM
Insert a new field before existing form fields
See "insert_before" in HTML::FormFu and "insert_after" in HTML::FormFu.
my $fieldset = $form->get_element({ type => 'Fieldset' });
$fieldset->insert_before(
$form->element(\%specs),
$form->get_field($name)
);
Another way to approach the problem is to use multiple config files,
and decide which to load at runtime:
# user_edit.yml
---
elements:
- type: Text
name: email
# user_username.yml
---
elements:
- type: Text
name: username
# user_register.yml
---
load_config_file:
- user_username.yml
- user_edit.yml
# create a user edit form, with only the email field
$form->load_config_file( 'user_edit.yml' );
# create a user registration form with username and email fields
$form->load_config_file( 'user_register.yml' );
From and Field attributes
You can add any arbitrary attributes to a form with "attributes" in
HTML::FormFu, or to any element with "attributes" in
HTML::FormFu::Element.
---
attributes_xml:
onsubmit: "js_function()"
elements:
- type: Text
name: foo
attributes_xml:
onchange: "js_function()"
FORM VALIDATION
Check valid dates
Use HTML::FormFu::Inflator::DateTime. When the inflator is processed,
it will try to create a DateTime object. An error will be returned if
the supplied values do not make a valid date.
Check valid URI / URLs
HTML::FormFu::Constraint::Regex supports Regexp::Common regular
expressions:
---
elements:
- type: Text
name: uri
constraints:
- type: Regex
common: [ URI, HTTP, { '-scheme': 'ftp|https?' ]
Implement a custom constraint / validator
If HTML::FormFu::Constraint::Callback or
HTML::FormFu::Validator::Callback isn't sufficient for your needs, you
can create your own class that inherits from HTML::FormFu::Constraint
or HTML::FormFu::Validator, respectively.
It should implement a "validate_value" method, which returns true is
the value is valid, or false otherwise.
package My::Custom::Validator;
use strict;
use base 'HTML::FormFu::Validator';
sub validate_value {
my ( $self, $value, $params ) = @_;
return 1 if value_is_valid( $value );
return;
}
1;
Then add your custom validator to the form:
---
elements:
- type: Text
name: foo
validators:
- '+My::Custom::Validator'
Constrain one form field based on the value of another
For example, you have a radiogroup and several text fields, with
different text fields being required depending on the value of the
radiogroup.
This is achieved using the "when" attribute of a constraint:
constraints:
- type: Length
min: 8
when:
field: bar
values: [ 1, 3, 5 ]
In the above example, the Length constraint is only processed when the
form field named "bar" has a value of either 1, 3 or 5.
You can also test for a negative condition using the "not" attribute:
constraints:
- type: Length
min: 8
when:
field: bar
values: [ 1, 3, 5 ]
not: 1
Now the constraint will be processed only if the value of field "bar"
is NOT 1, 3 or 5.
Note: if you rely on the value of a checkbox for a when-restricted
contraint, you might want to consider setting "default_empty_value" for
that checkbox. Take a look at HTML::FormFu::Element::_Field to learn
more.
Please read HTML::FormFu::Constraint for futher information.
Constrain one form field based on the return value of a callback
You can use the "when" attribute of a constraint also to decide using a
callback if the constraint should be applied.
For instance, the following (code) example shows a constraint being
applied only if the value of another field contains a pattern
my $apply_if_pattern = sub {
my $params = shift;
return 1 if $params->{other_field} =~ m/\A ice_cream \z/xms;
return 0;
}
$field->{constraints} = {
type => 'Required',
when => {
callback => $apply_if_pattern,
}
}
Please read HTML::FormFu::Constraint for futher information.
HTML MARKUP
Indented HTML
Use HTML::FormFu::OutputProcessor::Indent:
---
output_processors:
- Indent
Add a blank div (e.g. for AJAX purposes)
Simply add a Block element in the relevant place, it defaults to a
"DIV" tag.
---
elements:
- type: Text
name: user
- type: Block
id: foo
- type: Text
name: email
DISPLAY
Custom error messages
If you want to display an error message due to an error in your own
code, such as a database check; something which isn't implemented as a
Constraint or Validator; you can use a Callback Constraint.
If you don't provide your own callback routine, the default callback
will always pass, regardless of user input.
You can take advantage of this by setting force_errors, to display its
error message when needed.
Example config:
---
elements:
- type: Text
- name: email
- constraints:
type: Callback
message: 'Email address already in use'
Example usage:
if ( $@ =~ m/duplicate entry for key 'email'/i ) {
$form->get_field('email')
->get_constraint({ type => 'Callback' })
->force_errors(1);
$form->process;
# then redisplay the form as normal
}
Highlight required fields (or fields with certain types of constraint)
This can be achieved using the form's "auto_constraint_class" method:
$form->auto_constraint_class( 'constraint_%t' );
The container divs around any form field with a constraint will then
have extra CSS classes added, which indicate the type of constraint and
allow you to apply appropriate styling with CSS:
/* change background of labels for fields with a Required constraint */
fieldset .constraint_required label {
background: #f00;
}
This technique can also be used to add content before or after the
fields in question (note this will not work in older browsers with more
limited CSS support such as IE6):
/* add an asterisk at the end of the label for required fields */
fieldset .constraint_required label:after {
content: '*'
}
Add a popup hint to a field
Some visual browsers (including IE6/7, Firefox, Opera 9) display a
tooltip when a user hovers their mouse pointer over an HTML element
with a "title" tag. Aural browsers may try to turn the content into
speech. You can take advantage of this behaviour to provide a hint to
the user about how to complete a form field.
elements:
- type: Text
name: country_name
label: Country Name
attributes:
title: Name of country
The above will provide a hint when the "country_name" field receives
focus. Or you could provide the hint for the container tag around both
field and label:
elements:
- type: Text
name: country_name
label: Country Name
container_attributes:
title: Name of country
Display filtered values
If you have a Filter on a field, such as
HTML::FormFu::Filter::Whitespace to strip leading / trailing
whitespace, then if you redisplay the form the field is normally
populated with the value the user originally entered.
If you would like the field to contain the filtered value, use
"render_processed_value" in HTML::FormFu.
Multiple forms using Catalyst::Controller::HTML::FormFu
Sometimes you need to display multiple forms on a single page. If you
try to use FormConfig on several actions in a chain, or similar, they
all use "$c->stash->{form}" to store the form, hence you only get the
last form.
One way to work around such problems is to do a little of the work
yourself:
In this example we have a login_form that we want on every page
# root/forms/login.yml:
---
indicator: username
elements:
-
type: Text
name: username
constraints:
- Required
...
We also have an edit-form
# root/forms/foo/edit.yml
---
indicator: foo
elements:
-
type: Text
name: foo
constraints:
- Required
...
In this example, we want the login form to appear on every page, so we
load this in the top-most auto action:
package MyApp::Controller::Root;
BEGIN { extends 'Catalyst::Controller::HTML::FormFu'; }
sub auto : Private {
my ($self, $c) = @_;
# We want to utilize alot of the magic that the controller
# gives us, so therefore we call $self->form like this
my $login_form = $self->form;
$login_form->load_config_file('login.yml');
# Notice how we put it into another stash var, not 'form'
$c->stash->{login_form} = $login_form;
unless ($c->user_exists) {
$login_form->process();
if ($login_form->submitted_and_valid) {
# Since we set indicator, we should only end up here if we
# have a username in the form
$c->authenticate({
username => $login_form->param_value('username'),
password => $login_form->param_value('password'),
});
}
}
}
Any other page that wants to load another form, can now do so freely:
package MyApp::Controller::Foo;
sub edit : Local FormConfig {
my ( $self, $c ) = @_;
my $form = $c->stash->{form};
if ($form->submitted_and_valid) {
# Do whatever you want with it :p
}
}
In the view we now have two stash-variables:
In root/foo/edit.tt:
[% login_form %]
<h2>edit</h2>
[% form %]
ADVANCED CUSTOMISATION
Installing the TT templates
It only makes sense to use the template files if you plan on
customising them, as the default "string" render-method is faster.
If you're using the Catalyst web framework, install
Catalyst::Controller::HTML::FormFu and run the following command:
$ script/myapp_create.pl HTML::FormFu
This will create a directory, "root/formfu", containing the
HTML::FormFu template files.
If you use Catalyst::Controller::HTML::FormFu as a base class and you
don't set HTML::FormFu's INCLUDE_PATH yourself, it will automatically
be set to "root/formfu" if that directory exists.
If you're not using Catalyst, you can create the template files by
running the following command:
$ html_formfu_deploy.pl <target-directory>
Take note that if you choose to customise your own copy of
HTML::FormFu's template files, you'll need to keep track of the
"Changes" file, when updating HTML::FormFu, so that you can update your
own templates if the core templates are updated.
PERFORMANCE
Catalyst::Plugin::StackTrace
If you're using Catalyst::Plugin::StackTrace, make sure you're using at
least version 0.09 - earlier versions had performance problems with
"HTML::FormFu".
Template::Alloy
You can also use Template::Alloy instead of Template::Toolkit, it's
mostly compatible, and in many cases provides a reasonable speed
increase. You can do this either by setting the
"HTML_FORMFU_TEMPLATE_ALLOY" environment variable to a true value, or
by passing "TEMPLATE_ALLOY" to "tt_args" in HTML::FormFu:
tt_args:
TEMPLATE_ALLOY: 1
COMPILE_DIR: /tmp
COMPILE_PERL: 1
Template::Alloy's caching is off by default. Switch it on by setting
either "COMPILE_EXT" or "COMPILE_DIR". If you're running under a
persistent environment such as modperl or fastcgi, you should also set
"COMPILE_PERL" to compile the cached templates down to perl code.
Of cource, if you wish you can still use Template::Toolkit to process
your own application templates, letting Template::Alloy process just
the HTML::FormFu templates.
HTML:FormFu::Preload
To reduce the runtime for each form that uses a previously unused
element or processor - at the expense of greater memory usage - you can
preload all FormFu modules - this is only recommended for persistent
environments such as modperl or fastcgi:
use HTML::FormFu::Preload;
FAQs
Force an element to always have a certain value
See the following:
"retain_default" in HTML::FormFu::Element::_Field, "force_default" in
HTML::FormFu::Element::_Field
AUTHORS
Will Hawes "wdhawes@gmail.com"
Carl Franks "cfranks@cpan.org"
COPYRIGHT
This document is free, you can redistribute it and/or modify it under
the same terms as Perl itself.
perl v5.14.2 2011-05-10 HTML::FormFu::Manual::Cookbook(3)
