CGI-FormBuilder
view release on metacpan or search on metacpan
lib/CGI/FormBuilder.pod view on Meta::CPAN
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<HTML::Template>,
C<Text::Template>, C<Template Toolkit>, and C<CGI::FastTemplate>.
=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 <fieldsets>
font => $font | \%attr, # 'arial,helvetica'
jsfunc => $jscode, # JS code into validate()
jshead => $jscode, # JS code into <head>
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 <table>?
td => \%attr, # <td> options
tr => \%attr, # <tr> 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 <input>
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 <fieldset>
force => 0 | 1, # override CGI value?
growable => 0 | 1 | $limit, # expand text/file inputs?
jsclick => $jscode, # instead of onclick
jsmessage => $string, # on JS validation failure
message => $string, # other validation failure
other => 0 | 1, # create "Other:" input?
required => 0 | 1, # must fill field in?
validate => '/regex/', # validate user input
# HTML formatting options
cleanopts => 0 | 1, # HTML-escape options?
columns => 0 | $width, # wrap field options at $width
comment => $string, # printed after field
disabled => 0 | 1, # display as grayed-out?
labels => \%hash, # deprecated (use "options")
linebreaks => 0 | 1, # insert breaks in options?
nameopts => 0 | 1, # auto-name options?
lib/CGI/FormBuilder.pod view on Meta::CPAN
This is useful if you want to keep some extra parameters like mode or
company available but not have them be valid form fields:
keepextras => 1
That will preserve any extra params. You can also specify an arrayref,
in which case only params in that list will be preserved. For example:
keepextras => [qw(mode company)]
Will only preserve the params C<mode> and C<company>. Again, to access them:
my $mode = $form->cgi_param('mode');
$form->cgi_param(name => 'mode', value => 'relogin');
See C<CGI.pm> for details on C<param()> usage.
=item labels => \%hash
Like C<values>, this is a list of key/value pairs where the keys
are the names of C<fields> specified above. By default, B<FormBuilder>
does some snazzy case and character conversion to create pretty labels
for you. However, if you want to explicitly name your fields, use this
option.
For example:
my $form = CGI::FormBuilder->new(
fields => [qw(name email)],
labels => {
name => 'Your Full Name',
email => 'Primary Email Address'
}
);
Usually you'll find that if you're contemplating this option what
you really want is a template.
=item lalign => 'left' | 'right' | 'center'
A legacy shortcut for:
th => { align => 'left' }
Even better, use the C<stylesheet> option and tweak the C<.fb_label>
class. Either way, don't use this.
=item lang
This forcibly overrides the lang. Better handled by loading
an appropriate C<messages> module, which will set this for you.
See L<CGI::FormBuilder::Messages> for more details.
=item method => 'post' | 'get'
The type of CGI method to use, either C<post> or C<get>. Defaults
to C<get> if nothing is specified. Note that for forms that cause
changes on the server, such as database inserts, you should use
the C<post> method.
=item messages => 'auto' | $file | \%hash | $locale
This option overrides the default B<FormBuilder> messages in order to
provide multilingual locale support (or just different text for the picky ones).
For details on this option, please refer to L<CGI::FormBuilder::Messages>.
=item name => $string
This names the form. It is optional, but when used, it renames several
key variables and functions according to the name of the form. In addition,
it also adds the following C<< <div> >> tags to each row of the table:
<tr id="${form}_${field}_row">
<td id="${form}_${field}_label">Label</td>
<td id="${form}_${field}_input"><input tag></td>
<td id="${form}_${field}_error">Error</td><!-- if invalid -->
</tr>
These changes allow you to (a) use multiple forms in a sequential application
and/or (b) display multiple forms inline in one document. If you're trying
to build a complex multi-form app and are having problems, try naming
your forms.
=item options => \%hash
This is one of several I<meta-options> that allows you to specify
stuff for multiple fields at once:
my $form = CGI::FormBuilder->new(
fields => [qw(part_number department in_stock)],
options => {
department => [qw(hardware software)],
in_stock => [qw(yes no)],
}
);
This has the same effect as using C<field()> for the C<department>
and C<in_stock> fields to set options individually.
=item params => $object
This specifies an object from which the parameters should be derived.
The object must have a C<param()> method which will return values
for each parameter by name. By default a CGI object will be
automatically created and used.
However, you will want to specify this if you're using C<mod_perl>:
use Apache::Request;
use CGI::FormBuilder;
sub handler {
my $r = Apache::Request->new(shift);
my $form = CGI::FormBuilder->new(... params => $r);
print $form->render;
}
Or, if you need to initialize a C<CGI.pm> object separately and
are using a C<post> form method:
use CGI;
use CGI::FormBuilder;
my $q = new CGI;
( run in 1.431 second using v1.01-cache-2.11-cpan-ceb78f64989 )