=head1 NAME
CGI::FormBuilder - Easily generate and process stateful forms
=head1 SYNOPSIS
use CGI::FormBuilder;
# Assume we did a DBI query to get existing values
my $dbval = $sth->fetchrow_hashref;
# First create our form
my $form = CGI::FormBuilder->new(
name => 'acctinfo',
method => 'post',
stylesheet => '/path/to/style.css',
values => $dbval, # defaults
);
# Now create form fields, in order
# FormBuilder will automatically determine the type for you
$form->field(name => 'fname', label => 'First Name');
$form->field(name => 'lname', label => 'Last Name');
# Setup gender field to have options
$form->field(name => 'gender',
options => [qw(Male Female)] );
# Include validation for the email field
$form->field(name => 'email',
size => 60,
validate => 'EMAIL',
required => 1);
# And the (optional) phone field
$form->field(name => 'phone',
size => 10,
validate => '/^1?-?\d{3}-?\d{3}-?\d{4}$/',
comment => 'optional');
# Check to see if we're submitted and valid
if ($form->submitted && $form->validate) {
# Get form fields as hashref
my $field = $form->fields;
# Do something to update your data (you would write this)
do_data_update($field->{lname}, $field->{fname},
$field->{email}, $field->{phone},
$field->{gender});
# Show confirmation screen
print $form->confirm(header => 1);
} else {
# Print out the form
print $form->render(header => 1);
}
=head1 DESCRIPTION
If this is your first time using B, you should check out
the website for tutorials and examples at L.
You should also consider joining the google group at
L.
There are some pretty smart people on the list that can help you out.
=head2 Overview
I hate generating and processing forms. Hate it, hate it, hate it,
hate it. My forms almost always end up looking the same, and almost
always end up doing the same thing. Unfortunately, there haven't
really been any tools out there that streamline the process. Many
modules simply substitute Perl for HTML code:
# The manual way
print qq();
# The module way
print input(-name => 'email', -type => 'text', -size => '20');
The problem is, that doesn't really gain you anything - you still
have just as much code. Modules like C are great for
decoding parameters, but not for generating and processing whole forms.
The goal of CGI::FormBuilder (B) is to provide an easy way
for you to generate and process entire CGI form-based applications.
Its main features are:
=over
=item Field Abstraction
Viewing fields as entities (instead of just params), where the
HTML representation, CGI values, validation, and so on are properties
of each field.
=item DWIMmery
Lots of built-in "intelligence" (such as automatic field typing),
giving you about a 4:1 ratio of the code it generates versus what you
have to write.
=item Built-in Validation
Full-blown regex validation for fields, even including JavaScript
code generation.
=item Template Support
Pluggable support for external template engines, such as C,
C, C, and C.
=back
Plus, the native HTML generated is valid XHTML 1.0 Transitional.
=head2 Quick Reference
For the incredibly impatient, here's the quickest reference you can get:
# Create form
my $form = CGI::FormBuilder->new(
# Important options
fields => \@array | \%hash, # define form fields
header => 0 | 1, # send Content-type?
method => 'post' | 'get', # default is get
name => $string, # namespace (recommended)
reset => 0 | 1 | $str, # "Reset" button
submit => 0 | 1 | $str | \@array, # "Submit" button(s)
text => $text, # printed above form
title => $title, # printed up top
required => \@array | 'ALL' | 'NONE', # required fields?
values => \%hash | \@array, # from DBI, session, etc
validate => \%hash, # automatic field validation
# Lesser-used options
action => $script, # not needed (loops back)
cookies => 0 | 1, # use cookies for sessionid?
debug => 0 | 1 | 2 | 3, # gunk into error_log?
fieldsubs => 0 | 1, # allow $form->$field()
javascript => 0 | 1 | 'auto', # generate JS validate() code?
keepextras => 0 | 1 | \@array, # keep non-field params?
params => $object, # instead of CGI.pm
sticky => 0 | 1, # keep CGI values "sticky"?
messages => $file | \%hash | $locale | 'auto',
template => $file | \%hash | $object, # custom HTML
# HTML formatting and JavaScript options
body => \%attr, # {background => 'black'}
disabled => 0 | 1, # display as grayed-out?
fieldsets => \@arrayref # split form into
font => $font | \%attr, # 'arial,helvetica'
jsfunc => $jscode, # JS code into validate()
jshead => $jscode, # JS code into
linebreaks => 0 | 1, # put breaks in form?
selectnum => $threshold, # for auto-type generation
smartness => 0 | 1 | 2, # tweak "intelligence"
static => 0 | 1 | 2, # show non-editable form?
styleclass => $string, # style class to use ("fb")
stylesheet => 0 | 1 | $path, # turn on style class=
table => 0 | 1 | \%attr, # wrap form in
?
td => \%attr, #
options
tr => \%attr, #
options
# These are deprecated and you should use field() instead
fieldtype => 'type',
fieldattr => \%attr,
labels => \%hash,
options => \%hash,
sortopts => 'NAME' | 'NUM' | 1 | \&sub,
# External source file (see CGI::FormBuilder::Source::File)
source => $file,
);
# Tweak fields individually
$form->field(
# Important options
name => $name, # name of field (required)
label => $string, # shown in front of
type => $type, # normally auto-determined
multiple => 0 | 1, # allow multiple values?
options => \@options | \%options, # radio/select/checkbox
value => $value | \@values, # default value
# Lesser-used options
fieldset => $string, # put field into