\& User Information
\& Please fill out the following information:
\&
\& Your full name:
\& Your email address:
\& Choose a password:
\& Please confirm it:
\& Your home zipcode:
\&
\&
\&
.Ve
.PP
Then, all we need to do add the \f(CW\*(C`template\*(C'\fR option, and the rest of
the code stays the same:
.PP
.Vb 9
\& my $form = CGI::FormBuilder\->new(
\& fields => \e@fields,
\& header => 1,
\& validate => {
\& name => \*(AqNAME\*(Aq,
\& email => \*(AqEMAIL\*(Aq
\& },
\& template => \*(Aquserinfo.tmpl\*(Aq
\& );
.Ve
.PP
So, our complete code thus far looks like this:
.PP
.Vb 1
\& use CGI::FormBuilder;
\&
\& my @fields = qw(name email password confirm_password zipcode);
\&
\& my $form = CGI::FormBuilder\->new(
\& fields => \e@fields,
\& header => 1,
\& validate => {
\& name => \*(AqNAME\*(Aq,
\& email => \*(AqEMAIL\*(Aq
\& },
\& template => \*(Aquserinfo.tmpl\*(Aq,
\& );
\&
\& if ($form\->submitted && $form\->validate) {
\& # form was good, let\*(Aqs update database
\& my $fields = $form\->field;
\&
\& # update database (you write this part)
\& do_data_update($fields);
\&
\& # print confirmation screen
\& print $form\->confirm;
\&
\& } else {
\& # print the form for them to fill out
\& print $form\->render;
\& }
.Ve
.PP
You may be surprised to learn that for many applications, the
above is probably all you'll need. Just fill in the parts that
affect what you want to do (like the database code), and you're
on your way.
.PP
\&\fBNote:\fR If you are confused at all by the backslashes you see
in front of some data pieces above, such as \f(CW\*(C`\e@fields\*(C'\fR, skip down
to the brief section entitled "REFERENCES" at the bottom of this
document (it's short).
.SH METHODS
.IX Header "METHODS"
This documentation is very extensive, but can be a bit dizzying due
to the enormous number of options that let you tweak just about anything.
As such, I recommend that you stop and visit:
.PP
.Vb 1
\& www.formbuilder.org
.Ve
.PP
And click on "Tutorials" and "Examples". Then, use the following section
as a reference later on.
.SS \fBnew()\fP
.IX Subsection "new()"
This method creates a new \f(CW$form\fR object, which you then use to generate
and process your form. In the very shortest version, you can just specify
a list of fields for your form:
.PP
.Vb 3
\& my $form = CGI::FormBuilder\->new(
\& fields => [qw(first_name birthday favorite_car)]
\& );
.Ve
.PP
As of 3.02:
.PP
.Vb 3
\& my $form = CGI::FormBuilder\->new(
\& source => \*(Aqmyform.conf\*(Aq # form and field options
\& );
.Ve
.PP
For details on the external file format, see CGI::FormBuilder::Source::File.
.PP
Any of the options below, in addition to being specified to \f(CWnew()\fR, can
also be manipulated directly with a method of the same name. For example,
to change the \f(CW\*(C`header\*(C'\fR and \f(CW\*(C`stylesheet\*(C'\fR options, either of these works:
.PP
.Vb 6
\& # Way 1
\& my $form = CGI::FormBuilder\->new(
\& fields => \e@fields,
\& header => 1,
\& stylesheet => \*(Aq/path/to/style.css\*(Aq,
\& );
\&
\& # Way 2
\& my $form = CGI::FormBuilder\->new(
\& fields => \e@fields
\& );
\& $form\->header(1);
\& $form\->stylesheet(\*(Aq/path/to/style.css\*(Aq);
.Ve
.PP
The second form is useful if you want to wrap certain options in
conditionals:
.PP
.Vb 7
\& if ($have_template) {
\& $form\->header(0);
\& $form\->template(\*(Aqtemplate.tmpl\*(Aq);
\& } else {
\& $form\->header(1);
\& $form\->stylesheet(\*(Aq/path/to/style.css\*(Aq);
\& }
.Ve
.PP
The following is a description of each option, in alphabetical order:
.ie n .IP "action => $script" 4
.el .IP "action => \f(CW$script\fR" 4
.IX Item "action => $script"
What script to point the form to. Defaults to itself, which is
the recommended setting.
.IP "body => \e%attr" 4
.IX Item "body => %attr"
This takes a hashref of attributes that will be stuck in the
\&\f(CW\*(C`\*(C'\fR tag verbatim (for example, bgcolor, alink, etc).
See the \f(CW\*(C`fieldattr\*(C'\fR tag for more details, and also the
\&\f(CW\*(C`template\*(C'\fR option.
.IP charset 4
.IX Item "charset"
This forcibly overrides the charset. Better handled by loading
an appropriate \f(CW\*(C`messages\*(C'\fR module, which will set this for you.
See CGI::FormBuilder::Messages for more details.
.IP "debug => 0 | 1 | 2 | 3" 4
.IX Item "debug => 0 | 1 | 2 | 3"
If set to 1, the module spits copious debugging info to STDERR.
If set to 2, it spits out even more gunk. 3 is too much. Defaults to 0.
.IP "fields => \e@array | \e%hash" 4
.IX Item "fields => @array | %hash"
As shown above, the \f(CW\*(C`fields\*(C'\fR option takes an arrayref of fields to use
in the form. The fields will be printed out in the same order they are
specified. This option is needed if you expect your form to have any fields,
and is \fIthe\fR central option to FormBuilder.
.Sp
You can also specify a hashref of key/value pairs. The advantage is
you can then bypass the \f(CW\*(C`values\*(C'\fR option. However, the big disadvantage
is you cannot control the order of the fields. This is ok if you're
using a template, but in real-life it turns out that passing a hashref
to \f(CW\*(C`fields\*(C'\fR is not very useful.
.IP "fieldtype => 'type'" 4
.IX Item "fieldtype => 'type'"
This can be used to set the default type for all fields in the form.
You can then override it on a per-field basis using the \f(CWfield()\fR method.
.IP "fieldattr => \e%attr" 4
.IX Item "fieldattr => %attr"
This option allows you to specify \fIany\fR HTML attribute and have it be
the default for all fields. This used to be good for stylesheets, but
now that there is a \f(CW\*(C`stylesheet\*(C'\fR option, this is fairly useless.
.IP "fieldsets => \e@attr" 4
.IX Item "fieldsets => @attr"
This allows you to define fieldsets for your form. Fieldsets are used
to group fields together. Fields are rendered in order, inside the
fieldset they belong to. If a field does not have a fieldset, it
is appended to the end of the form.
.Sp
To use fieldsets, specify an arrayref of \f(CW\*(C`\*(C'\fR names:
.Sp
.Vb 1
\& fieldsets => [qw(account preferences contacts)]
.Ve
.Sp
You can get a different \f(CW\*(C`\*(C'\fR tag if you specify a nested arrayref:
.Sp
.Vb 5
\& fieldsets => [
\& [ account => \*(AqAccount Information\*(Aq ],
\& [ preferences => \*(AqWebsite Preferences\*(Aq ],
\& [ contacts => \*(AqEmail and Phone Numbers\*(Aq ],
\& ]
.Ve
.Sp
If you're using the source file, that looks like this:
.Sp
.Vb 1
\& fieldsets: account=Account Information,preferences=...
.Ve
.Sp
Then, for each field, specify which fieldset it belongs to:
.Sp
.Vb 5
\& $form\->field(name => \*(Aqfirst_name\*(Aq, fieldset => \*(Aqaccount\*(Aq);
\& $form\->field(name => \*(Aqlast_name\*(Aq, fieldset => \*(Aqaccount\*(Aq);
\& $form\->field(name => \*(Aqemail_me\*(Aq, fieldset => \*(Aqpreferences\*(Aq);
\& $form\->field(name => \*(Aqhome_phone\*(Aq, fieldset => \*(Aqcontacts\*(Aq);
\& $form\->field(name => \*(Aqwork_phone\*(Aq, fieldset => \*(Aqcontacts\*(Aq);
.Ve
.Sp
You can also automatically create a new \f(CW\*(C`fieldset\*(C'\fR on the fly by
specifying a new one:
.Sp
.Vb 1
\& $form\->field(name => \*(Aqremember_me\*(Aq, fieldset => \*(Aqadvanced\*(Aq);
.Ve
.Sp
To set the \f(CW\*(C`\*(C'\fR in this case, you have two options.
First, you can just choose a more readable \f(CW\*(C`fieldset\*(C'\fR name:
.Sp
.Vb 2
\& $form\->field(name => \*(Aqremember_me\*(Aq,
\& fieldset => \*(AqAdvanced\*(Aq);
.Ve
.Sp
Or, you can change the name using the \f(CW\*(C`fieldset\*(C'\fR accessor:
.Sp
.Vb 1
\& $form\->fieldset(advanced => \*(AqAdvanced Options\*(Aq);
.Ve
.Sp
Note that fieldsets without fields are silently ignored, so you can
also just specify a huge list of possible fieldsets to \f(CWnew()\fR, and
then only add fields as you need them.
.IP "fieldsubs => 0 | 1" 4
.IX Item "fieldsubs => 0 | 1"
This allows autoloading of field names so you can directly access
them as:
.Sp
.Vb 1
\& $form\->$fieldname(opt => \*(Aqval\*(Aq);
.Ve
.Sp
Instead of:
.Sp
.Vb 1
\& $form\->field(name => $fieldname, opt => \*(Aqval\*(Aq);
.Ve
.Sp
Warning: If present, it will hide any attributes of the same name.
For example, if you define "name" field, you won't be able to
change your form's name dynamically. Also, you cannot use this
format to create new fields. Use with caution.
.ie n .IP "font => $font | \e%attr" 4
.el .IP "font => \f(CW$font\fR | \e%attr" 4
.IX Item "font => $font | %attr"
The font face to use for the form. This is output as a series of
\&\f(CW\*(C`\*(C'\fR tags for old browser compatibility, and will
properly nest them in all of the table elements. If you specify
a hashref instead of just a font name, then each key/value pair
will be taken as part of the \f(CW\*(C`\*(C'\fR tag:
.Sp
.Vb 1
\& font => {face => \*(Aqverdana\*(Aq, size => \*(Aq\-1\*(Aq, color => \*(Aqgray\*(Aq}
.Ve
.Sp
The above becomes:
.Sp
.Vb 1
\&
.Ve
.Sp
I used to use this all the time, but the \f(CW\*(C`stylesheet\*(C'\fR option
is \fBSO MUCH BETTER\fR. Trust me, take a day and learn the basics
of CSS, it's totally worth it.
.IP "header => 0 | 1" 4
.IX Item "header => 0 | 1"
If set to 1, a valid \f(CW\*(C`Content\-type\*(C'\fR header will be printed out,
along with a whole bunch of HTML \f(CW\*(C`\*(C'\fR code, a \f(CW\*(C`\*(C'\fR
tag, and so on. This defaults to 0, since often people end up using
templates or embedding forms in other HTML.
.IP "javascript => 0 | 1" 4
.IX Item "javascript => 0 | 1"
If set to 1, JavaScript is generated in addition to HTML, the
default setting.
.IP "jserror => 'function_name'" 4
.IX Item "jserror => 'function_name'"
If specified, this will get called instead of the standard JS
\&\f(CWalert()\fR function on error. The function signature is:
.Sp
.Vb 1
\& function_name(form, invalid, alertstr, invalid_fields)
.Ve
.Sp
The function can be named anything you like. A simple one might
look like this:
.Sp
.Vb 10
\& my $form = CGI::FormBuilder\->new(
\& jserror => \*(Aqfield_errors\*(Aq,
\& jshead => <<\*(AqEOJS\*(Aq,
\&function field_errors(form, invalid, alertstr, invalid_fields) {
\& // first reset all fields
\& for (var i=0; i < form.elements.length; i++) {
\& form.elements[i].className = \*(Aqnormal_field\*(Aq;
\& }
\& // now attach a special style class to highlight the field
\& for (var i=0; i < invalid_fields.length; i++) {
\& form.elements[invalid_fields[i]].className = \*(Aqinvalid_field\*(Aq;
\& }
\& alert(alertstr);
\& return false;
\&}
\&EOJS
\& );
.Ve
.Sp
Note that it should return false to prevent form submission.
.Sp
This can be used in conjunction with \f(CW\*(C`jsfunc\*(C'\fR, which can add
additional manual validations before \f(CW\*(C`jserror\*(C'\fR is called.
.ie n .IP "jsfunc => $jscode" 4
.el .IP "jsfunc => \f(CW$jscode\fR" 4
.IX Item "jsfunc => $jscode"
This is verbatim JavaScript that will go into the \f(CW\*(C`validate\*(C'\fR
JavaScript function. It is useful for adding your own validation
code, while still getting all the automatic hooks. If something fails,
you should do two things:
.Sp
.Vb 2
\& 1. append to the JavaScript string "alertstr"
\& 2. increment the JavaScript number "invalid"
.Ve
.Sp
For example:
.Sp
.Vb 6
\& my $jsfunc = <<\*(AqEOJS\*(Aq; # note single quote (see Hint)
\& if (form.password.value == \*(Aqpassword\*(Aq) {
\& alertstr += "Moron, you can\*(Aqt use \*(Aqpassword\*(Aq for your password!\e\en";
\& invalid++;
\& }
\& EOJS
\&
\& my $form = CGI::FormBuilder\->new(... jsfunc => $jsfunc);
.Ve
.Sp
Then, this code will be automatically called when form validation
is invoked. I find this option can be incredibly useful. Most often,
I use it to bypass validation on certain submit modes. The submit
button that was clicked is \f(CW\*(C`form._submit.value\*(C'\fR:
.Sp
.Vb 9
\& my $jsfunc = <<\*(AqEOJS\*(Aq; # note single quotes (see Hint)
\& if (form._submit.value == \*(AqDelete\*(Aq) {
\& if (confirm("Really DELETE this entry?")) return true;
\& return false;
\& } else if (form._submit.value == \*(AqCancel\*(Aq) {
\& // skip validation since we\*(Aqre cancelling
\& return true;
\& }
\& EOJS
.Ve
.Sp
Hint: To prevent accidental expansion of embedding strings and escapes,
you should put your \f(CW\*(C`HERE\*(C'\fR string in single quotes, as shown above.
.ie n .IP "jshead => $jscode" 4
.el .IP "jshead => \f(CW$jscode\fR" 4
.IX Item "jshead => $jscode"
If using JavaScript, you can also specify some JavaScript code
that will be included verbatim in the <head> section of the
document. I'm not very fond of this one, what you probably
want is the previous option.
.IP "keepextras => 0 | 1 | \e@array" 4
.IX Item "keepextras => 0 | 1 | @array"
If set to 1, then extra parameters not set in your fields declaration
will be kept as hidden fields in the form. However, you will need
to use \f(CWcgi_param()\fR, \fBNOT\fR \f(CWfield()\fR, to access the values.
.Sp
This is useful if you want to keep some extra parameters like mode or
company available but not have them be valid form fields:
.Sp
.Vb 1
\& keepextras => 1
.Ve
.Sp
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:
.Sp
.Vb 1
\& keepextras => [qw(mode company)]
.Ve
.Sp
Will only preserve the params \f(CW\*(C`mode\*(C'\fR and \f(CW\*(C`company\*(C'\fR. Again, to access them:
.Sp
.Vb 2
\& my $mode = $form\->cgi_param(\*(Aqmode\*(Aq);
\& $form\->cgi_param(name => \*(Aqmode\*(Aq, value => \*(Aqrelogin\*(Aq);
.Ve
.Sp
See \f(CW\*(C`CGI.pm\*(C'\fR for details on \f(CWparam()\fR usage.
.IP "labels => \e%hash" 4
.IX Item "labels => %hash"
Like \f(CW\*(C`values\*(C'\fR, this is a list of key/value pairs where the keys
are the names of \f(CW\*(C`fields\*(C'\fR specified above. By default, \fBFormBuilder\fR
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.
.Sp
For example:
.Sp
.Vb 7
\& my $form = CGI::FormBuilder\->new(
\& fields => [qw(name email)],
\& labels => {
\& name => \*(AqYour Full Name\*(Aq,
\& email => \*(AqPrimary Email Address\*(Aq
\& }
\& );
.Ve
.Sp
Usually you'll find that if you're contemplating this option what
you really want is a template.
.IP "lalign => 'left' | 'right' | 'center'" 4
.IX Item "lalign => 'left' | 'right' | 'center'"
A legacy shortcut for:
.Sp
.Vb 1
\& th => { align => \*(Aqleft\*(Aq }
.Ve
.Sp
Even better, use the \f(CW\*(C`stylesheet\*(C'\fR option and tweak the \f(CW\*(C`.fb_label\*(C'\fR
class. Either way, don't use this.
.IP lang 4
.IX Item "lang"
This forcibly overrides the lang. Better handled by loading
an appropriate \f(CW\*(C`messages\*(C'\fR module, which will set this for you.
See CGI::FormBuilder::Messages for more details.
.IP "method => 'post' | 'get'" 4
.IX Item "method => 'post' | 'get'"
The type of CGI method to use, either \f(CW\*(C`post\*(C'\fR or \f(CW\*(C`get\*(C'\fR. Defaults
to \f(CW\*(C`get\*(C'\fR if nothing is specified. Note that for forms that cause
changes on the server, such as database inserts, you should use
the \f(CW\*(C`post\*(C'\fR method.
.ie n .IP "messages => 'auto' | $file | \e%hash | $locale" 4
.el .IP "messages => 'auto' | \f(CW$file\fR | \e%hash | \f(CW$locale\fR" 4
.IX Item "messages => 'auto' | $file | %hash | $locale"
This option overrides the default \fBFormBuilder\fR messages in order to
provide multilingual locale support (or just different text for the picky ones).
For details on this option, please refer to CGI::FormBuilder::Messages.
.ie n .IP "name => $string" 4
.el .IP "name => \f(CW$string\fR" 4
.IX 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 \f(CW\*(C`<div>\*(C'\fR tags to each row of the table:
.Sp
.Vb 5
\& <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>
.Ve
.Sp
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.
.IP "options => \e%hash" 4
.IX Item "options => %hash"
This is one of several \fImeta-options\fR that allows you to specify
stuff for multiple fields at once:
.Sp
.Vb 7
\& my $form = CGI::FormBuilder\->new(
\& fields => [qw(part_number department in_stock)],
\& options => {
\& department => [qw(hardware software)],
\& in_stock => [qw(yes no)],
\& }
\& );
.Ve
.Sp
This has the same effect as using \f(CWfield()\fR for the \f(CW\*(C`department\*(C'\fR
and \f(CW\*(C`in_stock\*(C'\fR fields to set options individually.
.ie n .IP "params => $object" 4
.el .IP "params => \f(CW$object\fR" 4
.IX Item "params => $object"
This specifies an object from which the parameters should be derived.
The object must have a \f(CWparam()\fR method which will return values
for each parameter by name. By default a CGI object will be
automatically created and used.
.Sp
However, you will want to specify this if you're using \f(CW\*(C`mod_perl\*(C'\fR:
.Sp
.Vb 2
\& use Apache::Request;
\& use CGI::FormBuilder;
\&
\& sub handler {
\& my $r = Apache::Request\->new(shift);
\& my $form = CGI::FormBuilder\->new(... params => $r);
\& print $form\->render;
\& }
.Ve
.Sp
Or, if you need to initialize a \f(CW\*(C`CGI.pm\*(C'\fR object separately and
are using a \f(CW\*(C`post\*(C'\fR form method:
.Sp
.Vb 2
\& use CGI;
\& use CGI::FormBuilder;
\&
\& my $q = new CGI;
\& my $form = CGI::FormBuilder\->new(... params => $q);
.Ve
.Sp
Usually you don't need to do this, unless you need to access other
parameters outside of \fBFormBuilder\fR's control.
.IP "required => \e@array | 'ALL' | 'NONE'" 4
.IX Item "required => @array | 'ALL' | 'NONE'"
This is a list of those values that are required to be filled in.
Those fields named must be included by the user. If the \f(CW\*(C`required\*(C'\fR
option is not specified, by default any fields named in \f(CW\*(C`validate\*(C'\fR
will be required.
.Sp
In addition, the \f(CW\*(C`required\*(C'\fR option also takes two other settings,
the strings \f(CW\*(C`ALL\*(C'\fR and \f(CW\*(C`NONE\*(C'\fR. If you specify \f(CW\*(C`ALL\*(C'\fR, then all
fields are required. If you specify \f(CW\*(C`NONE\*(C'\fR, then none of them are
\&\fIin spite of what may be set via the "validate" option\fR.
.Sp
This is useful if you have fields that are optional, but that you
want to be validated if filled in:
.Sp
.Vb 5
\& my $form = CGI::FormBuilder\->new(
\& fields => qw[/name email/],
\& validate => { email => \*(AqEMAIL\*(Aq },
\& required => \*(AqNONE\*(Aq
\& );
.Ve
.Sp
This would make the \f(CW\*(C`email\*(C'\fR field optional, but if filled in then
it would have to match the \f(CW\*(C`EMAIL\*(C'\fR pattern.
.Sp
In addition, it is \fIvery\fR important to note that if the \f(CW\*(C`required\*(C'\fR
\&\fIand\fR \f(CW\*(C`validate\*(C'\fR options are specified, then they are taken as an
intersection. That is, only those fields specified as \f(CW\*(C`required\*(C'\fR
must be filled in, and the rest are optional. For example:
.Sp
.Vb 5
\& my $form = CGI::FormBuilder\->new(
\& fields => qw[/name email/],
\& validate => { email => \*(AqEMAIL\*(Aq },
\& required => [qw(name)]
\& );
.Ve
.Sp
This would make the \f(CW\*(C`name\*(C'\fR field mandatory, but the \f(CW\*(C`email\*(C'\fR field
optional. However, if \f(CW\*(C`email\*(C'\fR is filled in, then it must match the
builtin \f(CW\*(C`EMAIL\*(C'\fR pattern.
.ie n .IP "reset => 0 | 1 | $string" 4
.el .IP "reset => 0 | 1 | \f(CW$string\fR" 4
.IX Item "reset => 0 | 1 | $string"
If set to 0, then the "Reset" button is not printed. If set to
text, then that will be printed out as the reset button. Defaults
to printing out a button that says "Reset".
.ie n .IP "selectnum => $threshold" 4
.el .IP "selectnum => \f(CW$threshold\fR" 4
.IX Item "selectnum => $threshold"
This detects how \fBFormBuilder\fR's auto-type generation works. If a
given field has options, then it will be a radio group by default.
However, if more than \f(CW\*(C`selectnum\*(C'\fR options are present, then it will
become a select list. The default is 5 or more options. For example:
.Sp
.Vb 3
\& # This will be a radio group
\& my @opt = qw(Yes No);
\& $form\->field(name => \*(Aqanswer\*(Aq, options => \e@opt);
\&
\& # However, this will be a select list
\& my @states = qw(AK CA FL NY TX);
\& $form\->field(name => \*(Aqstate\*(Aq, options => \e@states);
\&
\& # Single items are checkboxes (allows unselect)
\& $form\->field(name => \*(Aqanswer\*(Aq, options => [\*(AqYes\*(Aq]);
.Ve
.Sp
There is no threshold for checkboxes since, if you think about it,
they are really a multi-radio select group. As such, a radio group
becomes a checkbox group if the \f(CW\*(C`multiple\*(C'\fR option is specified and
the field has \fIless\fR than \f(CW\*(C`selectnum\*(C'\fR options. Got it?
.IP "smartness => 0 | 1 | 2" 4
.IX Item "smartness => 0 | 1 | 2"
By default CGI::FormBuilder tries to be pretty smart for you, like
figuring out the types of fields based on their names and number
of options. If you don't want this behavior at all, set \f(CW\*(C`smartness\*(C'\fR
to \f(CW0\fR. If you want it to be \fBreally\fR smart, like figuring
out what type of validation routines to use for you, set it to
\&\f(CW2\fR. It defaults to \f(CW1\fR.
.IP "sortopts => BUILTIN | 1 | \e&sub" 4
.IX Item "sortopts => BUILTIN | 1 | &sub"
If specified to \f(CWnew()\fR, this has the same effect as the same-named
option to \f(CWfield()\fR, only it applies to all fields.
.ie n .IP "source => $filename" 4
.el .IP "source => \f(CW$filename\fR" 4
.IX Item "source => $filename"
You can use this option to initialize \fBFormBuilder\fR from an external
configuration file. This allows you to separate your field code from
your form layout, which is pretty cool. See CGI::FormBuilder::Source::File
for details on the format of the external file.
.IP "static => 0 | 1 | 2" 4
.IX Item "static => 0 | 1 | 2"
If set to 1, then the form will be output with static hidden fields.
If set to 2, then in addition fields without values will be omitted.
Defaults to 0.
.IP "sticky => 0 | 1" 4
.IX Item "sticky => 0 | 1"
Determines whether or not form values should be sticky across
submissions. This defaults to 1, meaning values are sticky. However,
you may want to set it to 0 if you have a form which does something
like adding parts to a database. See the "EXAMPLES" section for
a good example.
.ie n .IP "submit => 0 | 1 | $string | \e@array" 4
.el .IP "submit => 0 | 1 | \f(CW$string\fR | \e@array" 4
.IX Item "submit => 0 | 1 | $string | @array"
If set to 0, then the "Submit" button is not printed. It defaults
to creating a button that says "Submit" verbatim. If given an
argument, then that argument becomes the text to show. For example:
.Sp
.Vb 1
\& print $form\->render(submit => \*(AqDo Lookup\*(Aq);
.Ve
.Sp
Would make it so the submit button says "Do Lookup" on it.
.Sp
If you pass an arrayref of multiple values, you get a key benefit.
This will create multiple submit buttons, each with a different value.
In addition, though, when submitted only the one that was clicked
will be sent across CGI via some JavaScript tricks. So this:
.Sp
.Vb 1
\& print $form\->render(submit => [\*(AqAdd A Gift\*(Aq, \*(AqNo Thank You\*(Aq]);
.Ve
.Sp
Would create two submit buttons. Clicking on either would submit the
form, but you would be able to see which one was submitted via the
\&\f(CWsubmitted()\fR function:
.Sp
.Vb 1
\& my $clicked = $form\->submitted;
.Ve
.Sp
So if the user clicked "Add A Gift" then that is what would end up
in the variable \f(CW$clicked\fR above. This allows nice conditionality:
.Sp
.Vb 5
\& if ($form\->submitted eq \*(AqAdd A Gift\*(Aq) {
\& # show the gift selection screen
\& } elsif ($form\->submitted eq \*(AqNo Thank You\*(Aq)
\& # just process the form
\& }
.Ve
.Sp
See the "EXAMPLES" section for more details.
.ie n .IP "styleclass => $string" 4
.el .IP "styleclass => \f(CW$string\fR" 4
.IX Item "styleclass => $string"
The string to use as the \f(CW\*(C`style\*(C'\fR name, if the following option
is enabled.
.ie n .IP "stylesheet => 0 | 1 | $path" 4
.el .IP "stylesheet => 0 | 1 | \f(CW$path\fR" 4
.IX Item "stylesheet => 0 | 1 | $path"
This option turns on stylesheets in the HTML output by \fBFormBuilder\fR.
Each element is printed with the \f(CW\*(C`class\*(C'\fR of \f(CW\*(C`styleclass\*(C'\fR ("fb"
by default). It is up to you to provide the actual style definitions.
If you provide a \f(CW$path\fR rather than just a 1/0 toggle, then that
\&\f(CW$path\fR will be included in a \f(CW\*(C`<link>\*(C'\fR tag as well.
.Sp
The following tags are created by this option:
.Sp
.Vb 3
\& ${styleclass} top\-level table/form class
\& ${styleclass}_required labels for fields that are required
\& ${styleclass}_invalid any fields that failed validate()
.Ve
.Sp
If you're contemplating stylesheets, the best thing is to just turn
this option on, then see what's spit out.
.Sp
See the section on "STYLESHEETS" for more details on FormBuilder
style sheets.
.IP "table => 0 | 1 | \e%tabletags" 4
.IX Item "table => 0 | 1 | %tabletags"
By default \fBFormBuilder\fR decides how to layout the form based on
the number of fields, values, etc. You can force it into a table
by specifying \f(CW1\fR, or force it out of one with \f(CW0\fR.
.Sp
If you specify a hashref instead, then these will be used to
create the \f(CW\*(C`<table>\*(C'\fR tag. For example, to create a table
with no cellpadding or cellspacing, use:
.Sp
.Vb 1
\& table => {cellpadding => 0, cellspacing => 0}
.Ve
.Sp
Also, you can specify options to the \f(CW\*(C`<td>\*(C'\fR and \f(CW\*(C`<tr>\*(C'\fR
elements as well in the same fashion.
.ie n .IP "template => $filename | \e%hash | \e&sub | $object" 4
.el .IP "template => \f(CW$filename\fR | \e%hash | \e&sub | \f(CW$object\fR" 4
.IX Item "template => $filename | %hash | &sub | $object"
This points to a filename that contains an \f(CW\*(C`HTML::Template\*(C'\fR
compatible template to use to layout the HTML. You can also specify
the \f(CW\*(C`template\*(C'\fR option as a reference to a hash, allowing you to
further customize the template processing options, or use other
template engines.
.Sp
If \f(CW\*(C`template\*(C'\fR points to a sub reference, that routine is called
and its return value directly returned. If it is an object, then
that object's \f(CWrender()\fR routine is called and its value returned.
.Sp
For lots more information, please see CGI::FormBuilder::Template.
.ie n .IP "text => $text" 4
.el .IP "text => \f(CW$text\fR" 4
.IX Item "text => $text"
This is text that is included below the title but above the
actual form. Useful if you want to say something simple like
"Contact \f(CW$adm\fR for more help", but if you want lots of text
check out the \f(CW\*(C`template\*(C'\fR option above.
.ie n .IP "title => $title" 4
.el .IP "title => \f(CW$title\fR" 4
.IX Item "title => $title"
This takes a string to use as the title of the form.
.IP "values => \e%hash | \e@array" 4
.IX Item "values => %hash | @array"
The \f(CW\*(C`values\*(C'\fR option takes a hashref of key/value pairs specifying
the default values for the fields. These values will be overridden
by the values entered by the user across the CGI. The values are
used case-insensitively, making it easier to use DBI hashref records
(which are in upper or lower case depending on your database).
.Sp
This option is useful for selecting a record from a database or
hardwiring some sensible defaults, and then including them in the
form so that the user can change them if they wish. For example:
.Sp
.Vb 3
\& my $rec = $sth\->fetchrow_hashref;
\& my $form = CGI::FormBuilder\->new(fields => \e@fields,
\& values => $rec);
.Ve
.Sp
You can also pass an arrayref, in which case each value is used
sequentially for each field as specified to the \f(CW\*(C`fields\*(C'\fR option.
.ie n .IP "validate => \e%hash | $object" 4
.el .IP "validate => \e%hash | \f(CW$object\fR" 4
.IX Item "validate => %hash | $object"
This option takes either a hashref of key/value pairs or a
Data::FormValidator object.
.Sp
In the case of the hashref, each key is the
name of a field from the \f(CW\*(C`fields\*(C'\fR option, or the string \f(CW\*(C`ALL\*(C'\fR
in which case it applies to all fields. Each value is one of
the following:
.Sp
.Vb 6
\& \- a regular expression in \*(Aqquotes\*(Aq to match against
\& \- an arrayref of values, of which the field must be one
\& \- a string that corresponds to one of the builtin patterns
\& \- a string containing a literal code comparison to do
\& \- a reference to a sub to be used to validate the field
\& (the sub will receive the value to check as the first arg)
.Ve
.Sp
In addition, each of these can also be grouped together as:
.Sp
.Vb 2
\& \- a hashref containing pairings of comparisons to do for
\& the two different languages, "javascript" and "perl"
.Ve
.Sp
By default, the \f(CW\*(C`validate\*(C'\fR option also toggles each field to make
it required. However, you can use the \f(CW\*(C`required\*(C'\fR option to change
this, see it for more details.
.Sp
Let's look at a concrete example. Note that the javascript
validation is a negative match, while the perl validation
is a positive match.
.Sp
.Vb 10
\& my $form = CGI::FormBuilder\->new(
\& fields => [qw(
\& username password confirm_password
\& first_name last_name email
\& )],
\& validate => {
\& username => [qw(nate jim bob)],
\& first_name => \*(Aq/^\ew+$/\*(Aq, # note the
\& last_name => \*(Aq/^\ew+$/\*(Aq, # single quotes!
\& email => \*(AqEMAIL\*(Aq,
\& password => \e&check_password,
\& confirm_password => {
\& javascript => \*(Aq!= form.password.value\*(Aq, # neg
\& perl => \*(Aqeq $form\->field("password")\*(Aq, # pos
\& },
\& },
\& );
\&
\& # simple sub example to check the password
\& sub check_password ($) {
\& my $v = shift; # first arg is value
\& return unless $v =~ /^.{6,8}/; # 6\-8 chars
\& return if $v eq "password"; # dummy check
\& return unless passes_crack($v); # you write "passes_crack()"
\& return 1; # success
\& }
.Ve
.Sp
This would create both JavaScript and Perl routines on the fly
that would ensure:
.Sp
.Vb 6
\& \- "username" was either "nate", "jim", or "bob"
\& \- "first_name" and "last_name" both match the regex\*(Aqs specified
\& \- "email" is a valid EMAIL format
\& \- "password" passes the checks done by check_password(), meaning
\& that the sub returns true
\& \- "confirm_password" is equal to the "password" field
.Ve
.Sp
\&\fBAny regular expressions you specify must be enclosed in single quotes
because they need to be used in both JavaScript and Perl code.\fR As
such, specifying a \f(CW\*(C`qr//\*(C'\fR will NOT work.
.Sp
Note that for both the \f(CW\*(C`javascript\*(C'\fR and \f(CW\*(C`perl\*(C'\fR hashref code options,
the form will be present as the variable named \f(CW\*(C`form\*(C'\fR. For the Perl
code, you actually get a complete \f(CW$form\fR object meaning that you
have full access to all its methods (although the \f(CWfield()\fR method
is probably the only one you'll need for validation).
.Sp
In addition to taking any regular expression you'd like, the
\&\f(CW\*(C`validate\*(C'\fR option also has many builtin defaults that can
prove helpful:
.Sp
.Vb 10
\& VALUE \- is any type of non\-null value
\& WORD \- is a word (\ew+)
\& NAME \- matches [a\-zA\-Z] only
\& FNAME \- person\*(Aqs first name, like "Jim" or "Joe\-Bob"
\& LNAME \- person\*(Aqs last name, like "Smith" or "King, Jr."
\& NUM \- number, decimal or integer
\& INT \- integer
\& FLOAT \- floating\-point number
\& PHONE \- phone number in form "123\-456\-7890" or "(123) 456\-7890"
\& INTPHONE\- international phone number in form "+prefix local\-number"
\& EMAIL \- email addr in form "name@host.domain"
\& CARD \- credit card, including Amex, with or without \-\*(Aqs
\& DATE \- date in format MM/DD/YYYY
\& EUDATE \- date in format DD/MM/YYYY
\& MMYY \- date in format MM/YY or MMYY
\& MMYYYY \- date in format MM/YYYY or MMYYYY
\& CCMM \- strict checking for valid credit card 2\-digit month ([0\-9]|1[012])
\& CCYY \- valid credit card 2\-digit year
\& ZIPCODE \- US postal code in format 12345 or 12345\-6789
\& STATE \- valid two\-letter state in all uppercase
\& IPV4 \- valid IPv4 address
\& NETMASK \- valid IPv4 netmask
\& FILE \- UNIX format filename (/usr/bin)
\& WINFILE \- Windows format filename (C:\ewindows\esystem)
\& MACFILE \- MacOS format filename (folder:subfolder:subfolder)
\& HOST \- valid hostname (some\-name)
\& DOMAIN \- valid domainname (www.i\-love\-bacon.com)
\& ETHER \- valid ethernet address using either : or . as separators
.Ve
.Sp
I know some of the above are US-centric, but then again that's where I live. :\-)
So if you need different processing just create your own regular expression
and pass it in. If there's something really useful let me know and maybe
I'll add it.
.Sp
You can also pass a Data::FormValidator object as the value of \f(CW\*(C`validate\*(C'\fR.
This allows you to do things like requiring any one of several fields (but
where you don't care which one). In this case, the \f(CW\*(C`required\*(C'\fR option to
\&\f(CWnew()\fR is ignored, since you should be setting the required fields through
your FormValidator profile.
.Sp
By default, FormBuilder will try to use a profile named `fb' to validate
itself. You can change this by providing a different profile name when you
call \f(CWvalidate()\fR.
.Sp
Note that currently, doing validation through a FormValidator object
doesn't generate any JavaScript validation code for you.
.PP
Note that any other options specified are passed to the \f(CW\*(C`<form>\*(C'\fR
tag verbatim. For example, you could specify \f(CW\*(C`onsubmit\*(C'\fR or \f(CW\*(C`enctype\*(C'\fR
to add the respective attributes.
.SS \fBprepare()\fP
.IX Subsection "prepare()"
This function prepares a form for rendering. It is automatically
called by \f(CWrender()\fR, but calling it yourself may be useful if
you are using \fBCatalyst\fR or some other large framework. It returns
the same hash that will be used by \f(CWrender()\fR:
.PP
.Vb 1
\& my %expanded = $form\->prepare;
.Ve
.PP
You could use this to, say, tweak some custom values and then
pass it to your own rendering object.
.SS \fBrender()\fP
.IX Subsection "render()"
This function renders the form into HTML, and returns a string
containing the form. The most common use is simply:
.PP
.Vb 1
\& print $form\->render;
.Ve
.PP
You can also supply options to \f(CWrender()\fR, just like you had
called the accessor functions individually. These two uses are
equivalent:
.PP
.Vb 4
\& # this code:
\& $form\->header(1);
\& $form\->stylesheet(\*(Aqstyle.css\*(Aq);
\& print $form\->render;
\&
\& # is the same as:
\& print $form\->render(header => 1,
\& stylesheet => \*(Aqstyle.css\*(Aq);
.Ve
.PP
Note that both forms make permanent changes to the underlying
object. So the next call to \f(CWrender()\fR will still have the
header and stylesheet options in either case.
.SS \fBfield()\fP
.IX Subsection "field()"
This method is used to both get at field values:
.PP
.Vb 1
\& my $bday = $form\->field(\*(Aqbirthday\*(Aq);
.Ve
.PP
As well as make changes to their attributes:
.PP
.Vb 2
\& $form\->field(name => \*(Aqfname\*(Aq,
\& label => "First Name");
.Ve
.PP
A very common use is to specify a list of options and/or the field type:
.PP
.Vb 3
\& $form\->field(name => \*(Aqstate\*(Aq,
\& type => \*(Aqselect\*(Aq,
\& options => \e@states); # you supply @states
.Ve
.PP
In addition, when you call \f(CWfield()\fR without any arguments, it returns
a list of valid field names in an array context:
.PP
.Vb 1
\& my @fields = $form\->field;
.Ve
.PP
And a hashref of field/value pairs in scalar context:
.PP
.Vb 2
\& my $fields = $form\->field;
\& my $name = $fields\->{name};
.Ve
.PP
Note that if you call it in this manner, you only get one single
value per field. This is fine as long as you don't have multiple
values per field (the normal case). However, if you have a field
that allows multiple options:
.PP
.Vb 2
\& $form\->field(name => \*(Aqcolor\*(Aq, options => \e@colors,
\& multiple => 1); # allow multi\-select
.Ve
.PP
Then you will only get one value for \f(CW\*(C`color\*(C'\fR in the hashref. In
this case you'll need to access it via \f(CWfield()\fR to get them all:
.PP
.Vb 1
\& my @colors = $form\->field(\*(Aqcolor\*(Aq);
.Ve
.PP
The \f(CW\*(C`name\*(C'\fR option is described first, and the remaining options
are in order:
.ie n .IP "name => $name" 4
.el .IP "name => \f(CW$name\fR" 4
.IX Item "name => $name"
The field to manipulate. The "name =>" part is optional if it's the
only argument. For example:
.Sp
.Vb 2
\& my $email = $form\->field(name => \*(Aqemail\*(Aq);
\& my $email = $form\->field(\*(Aqemail\*(Aq); # same thing
.Ve
.Sp
However, if you're specifying more than one argument, then you must
include the \f(CW\*(C`name\*(C'\fR part:
.Sp
.Vb 1
\& $form\->field(name => \*(Aqemail\*(Aq, size => \*(Aq40\*(Aq);
.Ve
.ie n .IP "add_after_option => $html" 4
.el .IP "add_after_option => \f(CW$html\fR" 4
.IX Item "add_after_option => $html"
Adds the specified HTML code after each checkbox (or radio) option.
.ie n .IP "add_before_option => $html" 4
.el .IP "add_before_option => \f(CW$html\fR" 4
.IX Item "add_before_option => $html"
Adds the specified HTML code before each checkbox (or radio) option.
.ie n .IP "columns => 0 | $width" 4
.el .IP "columns => 0 | \f(CW$width\fR" 4
.IX Item "columns => 0 | $width"
If set and the field is of type 'checkbox' or 'radio', then the
options will be wrapped at the given width.
.ie n .IP "comment => $string" 4
.el .IP "comment => \f(CW$string\fR" 4
.IX Item "comment => $string"
This prints out the given comment \fIafter\fR the field. A good use of
this is for additional help on what the field should contain:
.Sp
.Vb 3
\& $form\->field(name => \*(Aqdob\*(Aq,
\& label => \*(AqD.O.B.\*(Aq,
\& comment => \*(Aqin the format MM/DD/YY\*(Aq);
.Ve
.Sp
The above would yield something like this:
.Sp
.Vb 1
\& D.O.B. [_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_\|_] in the format MM/DD/YY
.Ve
.Sp
The comment is rendered verbatim, meaning you can use HTML links
or code in it if you want.
.IP "cleanopts => 0 | 1" 4
.IX Item "cleanopts => 0 | 1"
If set to 1 (the default), field options are escaped to make sure
any special chars don't screw up the HTML. Set to 0 if you want to
include verbatim HTML in your options, and know what you're doing.
.IP "cookies => 0 | 1" 4
.IX Item "cookies => 0 | 1"
Controls whether to generate a cookie if \f(CW\*(C`sessionid\*(C'\fR has been set.
This also requires that \f(CW\*(C`header\*(C'\fR be set as well, since the cookie
is wrapped in the header. Defaults to 1, meaning it will automatically
work if you turn on \f(CW\*(C`header\*(C'\fR.
.IP "force => 0 | 1" 4
.IX Item "force => 0 | 1"
This is used in conjunction with the \f(CW\*(C`value\*(C'\fR option to forcibly
override a field's value. See below under the \f(CW\*(C`value\*(C'\fR option for
more details. For compatibility with \f(CW\*(C`CGI.pm\*(C'\fR, you can also call
this option \f(CW\*(C`override\*(C'\fR instead, but don't tell anyone.
.ie n .IP "growable => 0 | 1 | $limit" 4
.el .IP "growable => 0 | 1 | \f(CW$limit\fR" 4
.IX Item "growable => 0 | 1 | $limit"
This option adds a button and the appropriate JavaScript code to
your form to allow the additional copies of the field to be added
by the client filling out the form. Currently, this only works with
\&\f(CW\*(C`text\*(C'\fR and \f(CW\*(C`file\*(C'\fR field types.
.Sp
If you set \f(CW\*(C`growable\*(C'\fR to a positive integer greater than 1, that
will become the limit of growth for that field. You won't be able
to add more than \f(CW$limit\fR extra inputs to the form, and FormBuilder
will issue a warning if the CGI params come in with more than the
allowed number of values.
.ie n .IP "jsclick => $jscode" 4
.el .IP "jsclick => \f(CW$jscode\fR" 4
.IX Item "jsclick => $jscode"
This is a cool abstraction over directly specifying the JavaScript
action. This turns out to be extremely useful, since if a field
type changes from \f(CW\*(C`select\*(C'\fR to \f(CW\*(C`radio\*(C'\fR or \f(CW\*(C`checkbox\*(C'\fR, then the
action changes from \f(CW\*(C`onchange\*(C'\fR to \f(CW\*(C`onclick\*(C'\fR. Why?!?!
.Sp
So if you said:
.Sp
.Vb 3
\& $form\->field(name => \*(Aqcredit_card\*(Aq,
\& options => \e@cards,
\& jsclick => \*(Aqrecalc_total();\*(Aq);
.Ve
.Sp
This would generate the following code, depending on the number
of \f(CW@cards\fR:
.Sp
.Vb 1
\& <select name="credit_card" onchange="recalc_total();"> ...
\&
\& <radio name="credit_card" onclick="recalc_total();"> ...
.Ve
.Sp
You get the idea.
.ie n .IP "jsmessage => $string" 4
.el .IP "jsmessage => \f(CW$string\fR" 4
.IX Item "jsmessage => $string"
You can use this to specify your own custom message for the field,
which will be printed if it fails validation. The \f(CW\*(C`jsmessage\*(C'\fR
option affects the JavaScript popup box, and the \f(CW\*(C`message\*(C'\fR option
affects what is printed out if the server-side validation fails.
If \f(CW\*(C`message\*(C'\fR is specified but not \f(CW\*(C`jsmessage\*(C'\fR, then \f(CW\*(C`message\*(C'\fR
will be used for JavaScript as well.
.Sp
.Vb 4
\& $form\->field(name => \*(Aqcc\*(Aq,
\& label => \*(AqCredit Card\*(Aq,
\& message => \*(AqInvalid credit card number\*(Aq,
\& jsmessage => \*(AqThe card number in "%s" is invalid\*(Aq);
.Ve
.Sp
The \f(CW%s\fR will be filled in with the field's \f(CW\*(C`label\*(C'\fR.
.ie n .IP "label => $string" 4
.el .IP "label => \f(CW$string\fR" 4
.IX Item "label => $string"
This is the label printed out before the field. By default it is
automatically generated from the field name. If you want to be
really lazy, get in the habit of naming your database fields as
complete words so you can pass them directly to/from your form.
.IP "labels => \e%hash" 4
.IX Item "labels => %hash"
\&\fBThis option to field() is outdated.\fR You can get the same effect by
passing data structures directly to the \f(CW\*(C`options\*(C'\fR argument (see below).
If you have well-named data, check out the \f(CW\*(C`nameopts\*(C'\fR option.
.Sp
This takes a hashref of key/value pairs where each key is one of
the options, and each value is what its printed label should be:
.Sp
.Vb 9
\& $form\->field(name => \*(Aqstate\*(Aq,
\& options => [qw(AZ CA NV OR WA)],
\& labels => {
\& AZ => \*(AqArizona\*(Aq,
\& CA => \*(AqCalifornia\*(Aq,
\& NV => \*(AqNevada\*(Aq,
\& OR => \*(AqOregon\*(Aq,
\& WA => \*(AqWashington
\& });
.Ve
.Sp
When rendered, this would create a select list where the option
values were "CA", "NV", etc, but where the state's full name
was displayed for the user to select. As mentioned, this has
the exact same effect:
.Sp
.Vb 8
\& $form\->field(name => \*(Aqstate\*(Aq,
\& options => [
\& [ AZ => \*(AqArizona\*(Aq ],
\& [ CA => \*(AqCalifornia\*(Aq ],
\& [ NV => \*(AqNevada\*(Aq ],
\& [ OR => \*(AqOregon\*(Aq ],
\& [ WA => \*(AqWashington ],
\& ]);
.Ve
.Sp
I can think of some rare situations where you might have a set
of predefined labels, but only some of those are present in a
given field... but usually you should just use the \f(CW\*(C`options\*(C'\fR arg.
.IP "linebreaks => 0 | 1" 4
.IX Item "linebreaks => 0 | 1"
Similar to the top-level "linebreaks" option, this one will put
breaks in between options, to space things out more. This is
useful with radio and checkboxes especially.
.ie n .IP "message => $string" 4
.el .IP "message => \f(CW$string\fR" 4
.IX Item "message => $string"
Like \f(CW\*(C`jsmessage\*(C'\fR, this customizes the output error string if
server-side validation fails for the field. The \f(CW\*(C`message\*(C'\fR
option will also be used for JavaScript messages if it is
specified but \f(CW\*(C`jsmessage\*(C'\fR is not. See above under \f(CW\*(C`jsmessage\*(C'\fR
for details.
.IP "multiple => 0 | 1" 4
.IX Item "multiple => 0 | 1"
If set to 1, then the user is allowed to choose multiple
values from the options provided. This turns radio groups
into checkboxes and selects into multi-selects. Defaults
to automatically being figured out based on number of values.
.IP "nameopts => 0 | 1" 4
.IX Item "nameopts => 0 | 1"
If set to 1, then options for select lists will be automatically
named using the same algorithm as field labels. For example:
.Sp
.Vb 6
\& $form\->field(name => \*(Aqdepartment\*(Aq,
\& options => qw[(molecular_biology
\& philosophy psychology
\& particle_physics
\& social_anthropology)],
\& nameopts => 1);
.Ve
.Sp
This would create a list like:
.Sp
.Vb 7
\& <select name="department">
\& <option value="molecular_biology">Molecular Biology</option>
\& <option value="philosophy">Philosophy</option>
\& <option value="psychology">Psychology</option>
\& <option value="particle_physics">Particle Physics</option>
\& <option value="social_anthropology">Social Anthropology</option>
\& </select>
.Ve
.Sp
Basically, you get names for the options that are determined in
the same way as the names for the fields. This is designed as
a simpler alternative to using custom \f(CW\*(C`options\*(C'\fR data structures
if your data is regular enough to support it.
.IP "other => 0 | 1 | \e%attr" 4
.IX Item "other => 0 | 1 | %attr"
If set, this automatically creates an "other" field to the right
of the main field. This is very useful if you want to present a
present list, but then also allow the user to enter their own
entry:
.Sp
.Vb 3
\& $form\->field(name => \*(Aqvote_for_president\*(Aq,
\& options => [qw(Bush Kerry)],
\& other => 1);
.Ve
.Sp
That would generate HTML somewhat like this:
.Sp
.Vb 1
\& Vote For President: [ ] Bush [ ] Kerry [ ] Other: [_\|_\|_\|_\|_\|_]
.Ve
.Sp
If the "other" button is checked, then the box becomes editable
so that the user can write in their own text. This "other" box
will be subject to the same validation as the main field, to
make sure your data for that field is consistent.
.IP "options => \e@options | \e%options | \e&sub" 4
.IX Item "options => @options | %options | &sub"
This takes an arrayref of options. It also automatically results
in the field becoming a radio (if < 5) or select list (if >= 5),
unless you explicitly set the type with the \f(CW\*(C`type\*(C'\fR parameter:
.Sp
.Vb 2
\& $form\->field(name => \*(Aqopinion\*(Aq,
\& options => [qw(yes no maybe so)]);
.Ve
.Sp
From that, you will get something like this:
.Sp
.Vb 6
\& <select name="opinion">
\& <option value="yes">yes</option>
\& <option value="no">no</option>
\& <option value="maybe">maybe</option>
\& <option value="so">so</option>
\& </select>
.Ve
.Sp
Also, this can accept more complicated data structures, allowing you to
specify different labels and values for your options. If a given item
is either an arrayref or hashref, then the first element will be
taken as the value and the second as the label. For example, this:
.Sp
.Vb 5
\& push @opt, [\*(Aqyes\*(Aq, \*(AqYou betcha!\*(Aq];
\& push @opt, [\*(Aqno\*(Aq, \*(AqNo way Jose\*(Aq];
\& push @opt, [\*(Aqmaybe\*(Aq, \*(AqPerchance...\*(Aq];
\& push @opt, [\*(Aqso\*(Aq, \*(AqSo\*(Aq];
\& $form\->field(name => \*(Aqopinion\*(Aq, options => \e@opt);
.Ve
.Sp
Would result in something like the following:
.Sp
.Vb 6
\& <select name="opinion">
\& <option value="yes">You betcha!</option>
\& <option value="no">No way Jose</option>
\& <option value="maybe">Perchance...</option>
\& <option value="so">So</option>
\& </select>
.Ve
.Sp
And this code would have the same effect:
.Sp
.Vb 5
\& push @opt, { yes => \*(AqYou betcha!\*(Aq };
\& push @opt, { no => \*(AqNo way Jose\*(Aq };
\& push @opt, { maybe => \*(AqPerchance...\*(Aq };
\& push @opt, { so => \*(AqSo\*(Aq };
\& $form\->field(name => \*(Aqopinion\*(Aq, options => \e@opt);
.Ve
.Sp
Finally, you can specify a \f(CW\*(C`\e&sub\*(C'\fR which must return either
an \f(CW\*(C`\e@arrayref\*(C'\fR or \f(CW\*(C`\e%hashref\*(C'\fR of data, which is then expanded
using the same algorithm.
.IP "optgroups => 0 | 1 | \e%hashref" 4
.IX Item "optgroups => 0 | 1 | %hashref"
If \f(CW\*(C`optgroups\*(C'\fR is specified for a field (\f(CW\*(C`select\*(C'\fR fields
only), then the above \f(CW\*(C`options\*(C'\fR array is parsed so that the
third argument is taken as the name of the optgroup, and an
\&\f(CW\*(C`<optgroup>\*(C'\fR tag is generated appropriately.
.Sp
An example will make this behavior immediately obvious:
.Sp
.Vb 4
\& my $opts = $dbh\->selectall_arrayref(
\& "select id, name, category from software
\& order by category, name"
\& );
\&
\& $form\->field(name => \*(Aqsoftware_title\*(Aq,
\& options => $opts,
\& optgroups => 1);
.Ve
.Sp
The \f(CW\*(C`optgroups\*(C'\fR setting would then parse the third element of
\&\f(CW$opts\fR so that you'd get an \f(CW\*(C`optgroup\*(C'\fR every time that
"category" changed:
.Sp
.Vb 9
\& <optgroup label="antivirus">
\& <option value="12">Norton Anti\-virus 1.2</option>
\& <option value="11">McAfee 1.1</option>
\& </optgroup>
\& <optgroup label="office">
\& <option value="3">Microsoft Word</option>
\& <option value="4">Open Office</option>
\& <option value="6">WordPerfect</option>
\& </optgroup>
.Ve
.Sp
In addition, if \f(CW\*(C`optgroups\*(C'\fR is instead a hashref, then the
name of the optgroup is gotten from that. Using the above example,
this would help if you had the category name in a separate table,
and were just storing the \f(CW\*(C`category_id\*(C'\fR in the \f(CW\*(C`software\*(C'\fR table.
You could provide an \f(CW\*(C`optgroups\*(C'\fR hash like:
.Sp
.Vb 6
\& my %optgroups = (
\& 1 => \*(Aqantivirus\*(Aq,
\& 2 => \*(Aqoffice\*(Aq,
\& 3 => \*(Aqmisc\*(Aq,
\& );
\& $form\->field(..., optgroups => \e%optgroups);
.Ve
.Sp
Note: No attempt is made by \fBFormBuilder\fR to properly sort
your option optgroups \- it is up to you to provide them in a
sensible order.
.IP "required => 0 | 1" 4
.IX Item "required => 0 | 1"
If set to 1, the field must be filled in:
.Sp
.Vb 1
\& $form\->field(name => \*(Aqemail\*(Aq, required => 1);
.Ve
.Sp
This is rarely useful \- what you probably want are the \f(CW\*(C`validate\*(C'\fR
and \f(CW\*(C`required\*(C'\fR options to \f(CWnew()\fR.
.ie n .IP "selectname => 0 | 1 | $string" 4
.el .IP "selectname => 0 | 1 | \f(CW$string\fR" 4
.IX Item "selectname => 0 | 1 | $string"
By default, this is set to \f(CW1\fR and any single-select lists are
prefixed by the message \f(CW\*(C`form_select_default\*(C'\fR ("\-select\-" for
English). If set to \f(CW0\fR, then this string is not prefixed.
If set to a \f(CW$string\fR, then that string is used explicitly.
.Sp
Philosophically, the "\-select\-" behavior is intentional because
it allows a null item to be transmitted (the same as not checking
any checkboxes or radio buttons). Otherwise, the first item in a
select list is automatically sent when the form is submitted.
If you would like an item to be "pre-selected", consider using
the \f(CW\*(C`value\*(C'\fR option to specify the default value.
.IP "sortopts => BUILTIN | 1 | \e&sub" 4
.IX Item "sortopts => BUILTIN | 1 | &sub"
If set, and there are options, then the options will be sorted
in the specified order. There are four possible values for the
\&\f(CW\*(C`BUILTIN\*(C'\fR setting:
.Sp
.Vb 4
\& NAME Sort option values by name
\& NUM Sort option values numerically
\& LABELNAME Sort option labels by name
\& LABELNUM Sort option labels numerically
.Ve
.Sp
For example:
.Sp
.Vb 3
\& $form\->field(name => \*(Aqcategory\*(Aq,
\& options => \e@cats,
\& sortopts => \*(AqNAME\*(Aq);
.Ve
.Sp
Would sort the \f(CW@cats\fR options in alphabetic (\f(CW\*(C`NAME\*(C'\fR) order.
The option \f(CW\*(C`NUM\*(C'\fR would sort them in numeric order. If you
specify "1", then an alphabetic sort is done, just like the
default Perl sort.
.Sp
In addition, you can specify a sub reference which takes pairs
of values to compare and returns the appropriate return value
that Perl \f(CWsort()\fR expects.
.ie n .IP "type => $type" 4
.el .IP "type => \f(CW$type\fR" 4
.IX Item "type => $type"
The type of input box to create. Default is "text", and valid values
include anything allowed by the HTML specs, including "select",
"radio", "checkbox", "textarea", "password", "hidden", and so on.
.Sp
By default, the type is automatically determined by \fBFormBuilder\fR
based on the following algorithm:
.Sp
.Vb 12
\& Field options?
\& No = text (done)
\& Yes:
\& Less than \*(Aqselectnum\*(Aq setting?
\& No = select (done)
\& Yes:
\& Is the \*(Aqmultiple\*(Aq option set?
\& Yes = checkbox (done)
\& No:
\& Have just one single option?
\& Yes = checkbox (done)
\& No = radio (done)
.Ve
.Sp
I recommend you let \fBFormBuilder\fR do this for you in most cases,
and only tweak those you really need to.
.ie n .IP "value => $value | \e@values" 4
.el .IP "value => \f(CW$value\fR | \e@values" 4
.IX Item "value => $value | @values"
The \f(CW\*(C`value\*(C'\fR option can take either a single value or an arrayref
of multiple values. In the case of multiple values, this will
result in the field automatically becoming a multiple select list
or radio group, depending on the number of options specified.
.Sp
\&\fBIf a CGI value is present it will always win.\fR To forcibly change
a value, you need to specify the \f(CW\*(C`force\*(C'\fR option:
.Sp
.Vb 3
\& # Example that hides credit card on confirm screen
\& if ($form\->submitted && $form\->validate) {
\& my $val = $form\->field;
\&
\& # hide CC number
\& $form\->field(name => \*(Aqcredit_card\*(Aq,
\& value => \*(Aq(not shown)\*(Aq,
\& force => 1);
\&
\& print $form\->confirm;
\& }
.Ve
.Sp
This would print out the string "(not shown)" on the \f(CWconfirm()\fR
screen instead of the actual number.
.IP "validate => '/regex/'" 4
.IX Item "validate => '/regex/'"
Similar to the \f(CW\*(C`validate\*(C'\fR option used in \f(CWnew()\fR, this affects
the validation just of that single field. As such, rather than
a hashref, you would just specify the regex to match against.
.Sp
\&\fBThis regex must be specified as a single-quoted string, and
NOT as a qr// regex\fR. The reason for this is it needs to be
usable by the JavaScript routines as well.
.ie n .IP "$htmlattr => $htmlval" 4
.el .IP "\f(CW$htmlattr\fR => \f(CW$htmlval\fR" 4
.IX Item "$htmlattr => $htmlval"
In addition to the above tags, the \f(CWfield()\fR function can take
any other valid HTML attribute, which will be placed in the tag
verbatim. For example, if you wanted to alter the class of the
field (if you're using stylesheets and a template, for example),
you could say:
.Sp
.Vb 2
\& $form\->field(name => \*(Aqemail\*(Aq, class => \*(AqFormField\*(Aq,
\& size => 80);
.Ve
.Sp
Then when you call \f(CW\*(C`$form\-\*(C'\fRrender> you would get a field something
like this:
.Sp
.Vb 1
\& <input type="text" name="email" class="FormField" size="80">
.Ve
.Sp
(Of course, for this to really work you still have to create a class
called \f(CW\*(C`FormField\*(C'\fR in your stylesheet.)
.Sp
See also the \f(CW\*(C`fieldattr\*(C'\fR option which provides global attributes
to all fields.
.SS \fBcgi_param()\fP
.IX Subsection "cgi_param()"
The above \f(CWfield()\fR method will only return fields which you have
\&\fIexplicitly\fR defined in your form. Excess parameters will be silently
ignored, to help ensure users can't mess with your form.
.PP
But, you may have some times when you want extra params so that
you can maintain state, but you don't want it to appear in your
form. Branding is an easy example:
.PP
.Vb 1
\& http://hr\-outsourcing.com/newuser.cgi?company=mr_propane
.Ve
.PP
This could change your page's HTML so that it displayed the
appropriate company name and logo, without polluting your
form parameters.
.PP
This call simply redispatches to \f(CW\*(C`CGI.pm\*(C'\fR's \f(CWparam()\fR method,
so consult those docs for more information.
.SS \fBtmpl_param()\fP
.IX Subsection "tmpl_param()"
This allows you to manipulate template parameters directly.
Extending the above example:
.PP
.Vb 1
\& my $form = CGI::FormBuilder\->new(template => \*(Aqsome.tmpl\*(Aq);
\&
\& my $company = $form\->cgi_param(\*(Aqcompany\*(Aq);
\& $form\->tmpl_param(company => $company);
.Ve
.PP
Then, in your template:
.PP
.Vb 5
\& Hello, <tmpl_var company> employee!
\& <p>
\& Please fill out this form:
\& <tmpl_var form\-start>
\& <!\-\- etc... \-\->
.Ve
.PP
For really precise template control, you can actually create your
own template object and then pass it directly to \fBFormBuilder\fR.
See CGI::FormBuilder::Template for more details.
.SS \fBsessionid()\fP
.IX Subsection "sessionid()"
This gets and sets the sessionid, which is stored in the special
form field \f(CW\*(C`_sessionid\*(C'\fR. By default no session ids are generated
or used. Rather, this is intended to provide a hook for you to
easily integrate this with a session id module like \f(CW\*(C`CGI::Session\*(C'\fR.
.PP
Since you can set the session id via the \f(CW\*(C`_sessionid\*(C'\fR field, you
can pass it as an argument when first showing the form:
.PP
.Vb 1
\& http://mydomain.com/forms/update_info.cgi?_sessionid=0123\-091231
.Ve
.PP
This would set things up so that if you called:
.PP
.Vb 1
\& my $id = $form\->sessionid;
.Ve
.PP
This would get the value \f(CW\*(C`0123\-091231\*(C'\fR in your script. Conversely,
if you generate a new sessionid on your own, and wish to include it
automatically, simply set is as follows:
.PP
.Vb 1
\& $form\->sessionid($id);
.Ve
.PP
If the sessionid is set, and \f(CW\*(C`header\*(C'\fR is set, then \fBFormBuilder\fR
will also automatically generate a cookie for you.
.PP
See "EXAMPLES" for \f(CW\*(C`CGI::Session\*(C'\fR example.
.SS \fBsubmitted()\fP
.IX Subsection "submitted()"
This returns the value of the "Submit" button if the form has been
submitted, undef otherwise. This allows you to either test it in
a boolean context:
.PP
.Vb 1
\& if ($form\->submitted) { ... }
.Ve
.PP
Or to retrieve the button that was actually clicked on in the
case of multiple submit buttons:
.PP
.Vb 5
\& if ($form\->submitted eq \*(AqUpdate\*(Aq) {
\& ...
\& } elsif ($form\->submitted eq \*(AqDelete\*(Aq) {
\& ...
\& }
.Ve
.PP
It's best to call \f(CWvalidate()\fR in conjunction with this to make
sure the form validation works. To make sure you're getting accurate
info, it's recommended that you name your forms with the \f(CW\*(C`name\*(C'\fR
option described above.
.PP
If you're writing a multiple-form app, you should name your forms
with the \f(CW\*(C`name\*(C'\fR option to ensure that you are getting an accurate
return value from this sub. See the \f(CW\*(C`name\*(C'\fR option above, under
\&\f(CWrender()\fR.
.PP
You can also specify the name of an optional field which you want to
"watch" instead of the default \f(CW\*(C`_submitted\*(C'\fR hidden field. This is useful
if you have a search form and also want to be able to link to it from
other documents directly, such as:
.PP
.Vb 1
\& mysearch.cgi?lookup=what+to+look+for
.Ve
.PP
Normally, \f(CWsubmitted()\fR would return false since the \f(CW\*(C`_submitted\*(C'\fR
field is not included. However, you can override this by saying:
.PP
.Vb 1
\& $form\->submitted(\*(Aqlookup\*(Aq);
.Ve
.PP
Then, if the lookup field is present, you'll get a true value.
(Actually, you'll still get the value of the "Submit" button if
present.)
.SS \fBvalidate()\fP
.IX Subsection "validate()"
This validates the form based on the validation criteria passed
into \f(CWnew()\fR via the \f(CW\*(C`validate\*(C'\fR option. In addition, you can
specify additional criteria to check that will be valid for just
that call of \f(CWvalidate()\fR. This is useful is you have to deal
with different geos:
.PP
.Vb 5
\& if ($location eq \*(AqUS\*(Aq) {
\& $form\->validate(state => \*(AqSTATE\*(Aq, zipcode => \*(AqZIPCODE\*(Aq);
\& } else {
\& $form\->validate(state => \*(Aq/^\ew{2,3}$/\*(Aq);
\& }
.Ve
.PP
You can also provide a Data::FormValidator object as the first
argument. In that case, the second argument (if present) will be
interpreted as the name of the validation profile to use. A single
string argument will also be interpreted as a validation profile
name.
.PP
Note that if you pass args to your \f(CWvalidate()\fR function like
this, you will not get JavaScript generated or required fields
placed in bold. So, this is good for conditional validation
like the above example, but for most applications you want to
pass your validation requirements in via the \f(CW\*(C`validate\*(C'\fR
option to the \f(CWnew()\fR function, and just call the \f(CWvalidate()\fR
function with no arguments.
.SS \fBconfirm()\fP
.IX Subsection "confirm()"
The purpose of this function is to print out a static confirmation
screen showing a short message along with the values that were
submitted. It is actually just a special wrapper around \f(CWrender()\fR,
twiddling a couple options.
.PP
If you're using templates, you probably want to specify a separate
success template, such as:
.PP
.Vb 5
\& if ($form\->submitted && $form\->validate) {
\& print $form\->confirm(template => \*(Aqsuccess.tmpl\*(Aq);
\& } else {
\& print $form\->render(template => \*(Aqfillin.tmpl\*(Aq);
\& }
.Ve
.PP
So that you don't get the same screen twice.
.SS \fBmailconfirm()\fP
.IX Subsection "mailconfirm()"
This sends a confirmation email to the named addresses. The \f(CW\*(C`to\*(C'\fR
argument is required; everything else is optional. If no \f(CW\*(C`from\*(C'\fR
is specified then it will be set to the address \f(CW\*(C`auto\-reply\*(C'\fR
since that is a common quasi-standard in the web app world.
.PP
This does not send any of the form results. Rather, it simply
prints out a message saying the submission was received.
.SS \fBmailresults()\fP
.IX Subsection "mailresults()"
This emails the form results to the specified address(es). By
default it prints out the form results separated by a colon, such as:
.PP
.Vb 3
\& name: Nate Wiger
\& email: nate@wiger.org
\& colors: red green blue
.Ve
.PP
And so on. You can change this by specifying the \f(CW\*(C`delimiter\*(C'\fR and
\&\f(CW\*(C`joiner\*(C'\fR options. For example this:
.PP
.Vb 1
\& $form\->mailresults(to => $to, delimiter => \*(Aq=\*(Aq, joiner => \*(Aq,\*(Aq);
.Ve
.PP
Would produce an email like this:
.PP
.Vb 3
\& name=Nate Wiger
\& email=nate@wiger.org
\& colors=red,green,blue
.Ve
.PP
Note that now the last field ("colors") is separated by commas since
you have multiple values and you specified a comma as your \f(CW\*(C`joiner\*(C'\fR.
.SS "\fBmailresults()\fP with plugin"
.IX Subsection "mailresults() with plugin"
Now you can also specify a plugin to use with mailresults, in
the namespace \f(CW\*(C`CGI::FormBuilder::Mail::*\*(C'\fR. These plugins may
depend on other libraries. For example, this:
.PP
.Vb 7
\& $form\->mailresults(
\& plugin => \*(AqFormatMultiPart\*(Aq,
\& from => \*(AqMark Hedges <hedges@ucsd.edu>\*(Aq,
\& to => \*(AqNate Wiger <nwiger@gmail.com>\*(Aq,
\& smtp => $smtp_host_or_ip,
\& format => \*(Aqplain\*(Aq,
\& );
.Ve
.PP
will send your mail formatted nicely in text using \f(CW\*(C`Text::FormatTable\*(C'\fR.
(And if you used format => 'html' it would use \f(CW\*(C`HTML::QuickTable\*(C'\fR.)
.PP
This particular plugin uses \f(CW\*(C`MIME::Lite\*(C'\fR and \f(CW\*(C`Net::SMTP\*(C'\fR to communicate
directly with the SMTP server, and does not rely on a shell escape.
See CGI::FormBuilder::Mail::FormatMultiPart for more information.
.PP
This establishes a simple mail plugin implementation standard
for your own \fBmailresults()\fR plugins. The plugin should reside
under the \f(CW\*(C`CGI::FormBuilder::Mail::*\*(C'\fR namespace. It should have
a constructor \fBnew()\fR which accepts a hash-as-array of named arg
parameters, including form => \f(CW$form\fR. It should have a \fBmailresults()\fR
object method that does the right thing. It should use
\&\f(CW\*(C`CGI::FormBuilder::Util\*(C'\fR and \fBpuke()\fR if something goes wrong.
.PP
Calling \f(CW$form\fR\->mailresults( plugin => 'Foo', ... ) will load
\&\f(CW\*(C`CGI::FormBuilder::Mail::Foo\*(C'\fR and will pass the FormBuilder object
as a named param 'form' with all other parameters passed intact.
.PP
If it should croak, confess, die or otherwise break if something
goes wrong, FormBuilder.pm will warn any errors and the built-in
\&\fBmailresults()\fR method will still try.
.SS \fBmail()\fP
.IX Subsection "mail()"
This is a more generic version of the above; it sends whatever is
given as the \f(CW\*(C`text\*(C'\fR argument via email verbatim to the \f(CW\*(C`to\*(C'\fR address.
In addition, if you're not running \f(CW\*(C`sendmail\*(C'\fR you can specify the
\&\f(CW\*(C`mailer\*(C'\fR parameter to give the path of your mailer. This option
is accepted by the above functions as well.
.SH COMPATIBILITY
.IX Header "COMPATIBILITY"
The following methods are provided to make \fBFormBuilder\fR behave more
like other modules, when desired.
.SS \fBheader()\fP
.IX Subsection "header()"
Returns a \f(CW\*(C`CGI.pm\*(C'\fR header, but only if \f(CW\*(C`header => 1\*(C'\fR is set.
.SS \fBparam()\fP
.IX Subsection "param()"
This is an alias for \f(CWfield()\fR, provided for compatibility. However,
while \f(CWfield()\fR \fIdoes\fR act "compliantly" for easy use in \f(CW\*(C`CGI::Session\*(C'\fR,
\&\f(CW\*(C`Apache::Request\*(C'\fR, etc, it is \fInot\fR 100% the same. As such, I recommend
you use \f(CWfield()\fR in your code, and let receiving objects figure the
\&\f(CWparam()\fR thing out when needed:
.PP
.Vb 2
\& my $sess = CGI::Session\->new(...);
\& $sess\->save_param($form); # will see param()
.Ve
.SS \fBquery_string()\fP
.IX Subsection "query_string()"
This returns a query string similar to \f(CW\*(C`CGI.pm\*(C'\fR, but \fBONLY\fR containing
form fields and any \f(CW\*(C`keepextras\*(C'\fR, if specified. Other params are ignored.
.SS \fBself_url()\fP
.IX Subsection "self_url()"
This returns a self url, similar to \f(CW\*(C`CGI.pm\*(C'\fR, but again \fBONLY\fR with
form fields.
.SS \fBscript_name()\fP
.IX Subsection "script_name()"
An alias for \f(CW\*(C`$form\->action\*(C'\fR.
.SH "STYLESHEETS (CSS)"
.IX Header "STYLESHEETS (CSS)"
If the \f(CW\*(C`stylesheet\*(C'\fR option is enabled (by setting it to 1 or the
path of a CSS file), then \fBFormBuilder\fR will automatically output
style classes for every single form element:
.PP
.Vb 4
\& fb main form table
\& fb_label td containing field label
\& fb_field td containing field input tag
\& fb_submit td containing submit button(s)
\&
\& fb_input input types
\& fb_select select types
\& fb_checkbox checkbox types
\& fb_radio radio types
\& fb_option labels for checkbox/radio options
\& fb_button button types
\& fb_hidden hidden types
\& fb_static static types
\&
\& fb_required span around labels for required fields
\& fb_invalid span around labels for invalid fields
\& fb_comment span around field comment
\& fb_error span around field error message
.Ve
.PP
Here's a simple example that you can put in \f(CW\*(C`fb.css\*(C'\fR which spruces
up a couple basic form features:
.PP
.Vb 6
\& /* FormBuilder */
\& .fb {
\& background: #ffc;
\& font\-family: verdana,arial,sans\-serif;
\& font\-size: 10pt;
\& }
\&
\& .fb_label {
\& text\-align: right;
\& padding\-right: 1em;
\& }
\&
\& .fb_comment {
\& font\-size: 8pt;
\& font\-style: italic;
\& }
\&
\& .fb_submit {
\& text\-align: center;
\& }
\&
\& .fb_required {
\& font\-weight: bold;
\& }
\&
\& .fb_invalid {
\& color: #c00;
\& font\-weight: bold;
\& }
\&
\& .fb_error {
\& color: #c00;
\& font\-style: italic;
\& }
.Ve
.PP
Of course, if you're familiar with CSS, you know alot more is possible.
Also, you can mess with all the id's (if you name your forms) to
manipulate fields more exactly.
.SH EXAMPLES
.IX Header "EXAMPLES"
I find this module incredibly useful, so here are even more examples,
pasted from sample code that I've written:
.SS "Ex1: order.cgi"
.IX Subsection "Ex1: order.cgi"
This example provides an order form, complete with validation of the
important fields, and a "Cancel" button to abort the whole thing.
.PP
.Vb 1
\& #!/usr/bin/perl
\&
\& use strict;
\& use CGI::FormBuilder;
\&
\& my @states = my_state_list(); # you write this
\&
\& my $form = CGI::FormBuilder\->new(
\& method => \*(Aqpost\*(Aq,
\& fields => [
\& qw(first_name last_name
\& email send_me_emails
\& address state zipcode
\& credit_card expiration)
\& ],
\&
\& header => 1,
\& title => \*(AqFinalize Your Order\*(Aq,
\& submit => [\*(AqPlace Order\*(Aq, \*(AqCancel\*(Aq],
\& reset => 0,
\&
\& validate => {
\& email => \*(AqEMAIL\*(Aq,
\& zipcode => \*(AqZIPCODE\*(Aq,
\& credit_card => \*(AqCARD\*(Aq,
\& expiration => \*(AqMMYY\*(Aq,
\& },
\& required => \*(AqALL\*(Aq,
\& jsfunc => <<EOJS,
\& // skip js validation if they clicked "Cancel"
\& if (this._submit.value == \*(AqCancel\*(Aq) return true;
\&EOJS
\& );
\&
\& # Provide a list of states
\& $form\->field(name => \*(Aqstate\*(Aq,
\& options => \e@states,
\& sortopts=> \*(AqNAME\*(Aq);
\&
\& # Options for mailing list
\& $form\->field(name => \*(Aqsend_me_emails\*(Aq,
\& options => [[1 => \*(AqYes\*(Aq], [0 => \*(AqNo\*(Aq]],
\& value => 0); # "No"
\&
\& # Check for valid order
\& if ($form\->submitted eq \*(AqCancel\*(Aq) {
\& # redirect them to the homepage
\& print $form\->cgi\->redirect(\*(Aq/\*(Aq);
\& exit;
\& }
\& elsif ($form\->submitted && $form\->validate) {
\& # your code goes here to do stuff...
\& print $form\->confirm;
\& }
\& else {
\& # either first printing or needs correction
\& print $form\->render;
\& }
.Ve
.PP
This will create a form called "Finalize Your Order" that will provide a
pulldown menu for the \f(CW\*(C`state\*(C'\fR, a radio group for \f(CW\*(C`send_me_emails\*(C'\fR, and
normal text boxes for the rest. It will then validate all the fields,
using specific patterns for those fields specified to \f(CW\*(C`validate\*(C'\fR.
.SS "Ex2: order_form.cgi"
.IX Subsection "Ex2: order_form.cgi"
Here's an example that adds some fields dynamically, and uses the
\&\f(CW\*(C`debug\*(C'\fR option spit out gook:
.PP
.Vb 1
\& #!/usr/bin/perl
\&
\& use strict;
\& use CGI::FormBuilder;
\&
\& my $form = CGI::FormBuilder\->new(
\& method => \*(Aqpost\*(Aq,
\& fields => [
\& qw(first_name last_name email
\& address state zipcode)
\& ],
\& header => 1,
\& debug => 2, # gook
\& required => \*(AqNONE\*(Aq,
\& );
\&
\& # This adds on the \*(Aqdetails\*(Aq field to our form dynamically
\& $form\->field(name => \*(Aqdetails\*(Aq,
\& type => \*(Aqtextarea\*(Aq,
\& cols => \*(Aq50\*(Aq,
\& rows => \*(Aq10\*(Aq);
\&
\& # And this adds user_name with validation
\& $form\->field(name => \*(Aquser_name\*(Aq,
\& value => $ENV{REMOTE_USER},
\& validate => \*(AqNAME\*(Aq);
\&
\& if ($form\->submitted && $form\->validate) {
\& # ... more code goes here to do stuff ...
\& print $form\->confirm;
\& } else {
\& print $form\->render;
\& }
.Ve
.PP
In this case, none of the fields are required, but the \f(CW\*(C`user_name\*(C'\fR
field will still be validated if filled in.
.SS "Ex3: ticket_search.cgi"
.IX Subsection "Ex3: ticket_search.cgi"
This is a simple search script that uses a template to layout
the search parameters very precisely. Note that we set our
options for our different fields and types.
.PP
.Vb 1
\& #!/usr/bin/perl
\&
\& use strict;
\& use CGI::FormBuilder;
\&
\& my $form = CGI::FormBuilder\->new(
\& fields => [qw(type string status category)],
\& header => 1,
\& template => \*(Aqticket_search.tmpl\*(Aq,
\& submit => \*(AqSearch\*(Aq, # search button
\& reset => 0, # and no reset
\& );
\&
\& # Need to setup some specific field options
\& $form\->field(name => \*(Aqtype\*(Aq,
\& options => [qw(ticket requestor hostname sysadmin)]);
\&
\& $form\->field(name => \*(Aqstatus\*(Aq,
\& type => \*(Aqradio\*(Aq,
\& options => [qw(incomplete recently_completed all)],
\& value => \*(Aqincomplete\*(Aq);
\&
\& $form\->field(name => \*(Aqcategory\*(Aq,
\& type => \*(Aqcheckbox\*(Aq,
\& options => [qw(server network desktop printer)]);
\&
\& # Render the form and print it out so our submit button says "Search"
\& print $form\->render;
.Ve
.PP
Then, in our \f(CW\*(C`ticket_search.tmpl\*(C'\fR HTML file, we would have something like this:
.PP
.Vb 10
\& <html>
\& <head>
\& <title>Search Engine
\&
\&
\&
\&
\&
\& Please enter a term to search the ticket database.
\&
\&
\& Search by for
\&
\&
\& Status:
\&
\& Category:
\&
\&
\&
\&
.Ve
.PP
That's all you need for a sticky search form with the above HTML layout.
Notice that you can change the HTML layout as much as you want without
having to touch your CGI code.
.SS "Ex4: user_info.cgi"
.IX Subsection "Ex4: user_info.cgi"
This script grabs the user's information out of a database and lets
them update it dynamically. The DBI information is provided as an
example, your mileage may vary:
.PP
.Vb 1
\& #!/usr/bin/perl
\&
\& use strict;
\& use CGI::FormBuilder;
\& use DBI;
\& use DBD::Oracle
\&
\& my $dbh = DBI\->connect(\*(Aqdbi:Oracle:db\*(Aq, \*(Aquser\*(Aq, \*(Aqpass\*(Aq);
\&
\& # We create a new form. Note we\*(Aqve specified very little,
\& # since we\*(Aqre getting all our values from our database.
\& my $form = CGI::FormBuilder\->new(
\& fields => [qw(username password confirm_password
\& first_name last_name email)]
\& );
\&
\& # Now get the value of the username from our app
\& my $user = $form\->cgi_param(\*(Aquser\*(Aq);
\& my $sth = $dbh\->prepare("select * from user_info where user = \*(Aq$user\*(Aq");
\& $sth\->execute;
\& my $default_hashref = $sth\->fetchrow_hashref;
\&
\& # Render our form with the defaults we got in our hashref
\& print $form\->render(values => $default_hashref,
\& title => "User information for \*(Aq$user\*(Aq",
\& header => 1);
.Ve
.SS "Ex5: add_part.cgi"
.IX Subsection "Ex5: add_part.cgi"
This presents a screen for users to add parts to an inventory database.
Notice how it makes use of the \f(CW\*(C`sticky\*(C'\fR option. If there's an error,
then the form is presented with sticky values so that the user can
correct them and resubmit. If the submission is ok, though, then the
form is presented without sticky values so that the user can enter
the next part.
.PP
.Vb 1
\& #!/usr/bin/perl
\&
\& use strict;
\& use CGI::FormBuilder;
\&
\& my $form = CGI::FormBuilder\->new(
\& method => \*(Aqpost\*(Aq,
\& fields => [qw(sn pn model qty comments)],
\& labels => {
\& sn => \*(AqSerial Number\*(Aq,
\& pn => \*(AqPart Number\*(Aq
\& },
\& sticky => 0,
\& header => 1,
\& required => [qw(sn pn model qty)],
\& validate => {
\& sn => \*(Aq/^[PL]\ed{2}\-\ed{4}\-\ed{4}$/\*(Aq,
\& pn => \*(Aq/^[AQM]\ed{2}\-\ed{4}$/\*(Aq,
\& qty => \*(AqINT\*(Aq
\& },
\& font => \*(Aqarial,helvetica\*(Aq
\& );
\&
\& # shrink the qty field for prettiness, lengthen model
\& $form\->field(name => \*(Aqqty\*(Aq, size => 4);
\& $form\->field(name => \*(Aqmodel\*(Aq, size => 60);
\&
\& if ($form\->submitted) {
\& if ($form\->validate) {
\& # Add part to database
\& } else {
\& # Invalid; show form and allow corrections
\& print $form\->render(sticky => 1);
\& exit;
\& }
\& }
\&
\& # Print form for next part addition.
\& print $form\->render;
.Ve
.PP
With the exception of the database code, that's the whole application.
.SS "Ex6: Session Management"
.IX Subsection "Ex6: Session Management"
This creates a session via \f(CW\*(C`CGI::Session\*(C'\fR, and ties it in with \fBFormBuilder\fR:
.PP
.Vb 1
\& #!/usr/bin/perl
\&
\& use CGI::Session;
\& use CGI::FormBuilder;
\&
\& my $form = CGI::FormBuilder\->new(fields => \e@fields);
\&
\& # Initialize session
\& my $session = CGI::Session\->new(\*(Aqdriver:File\*(Aq,
\& $form\->sessionid,
\& { Directory=>\*(Aq/tmp\*(Aq });
\&
\& if ($form\->submitted && $form\->validate) {
\& # Automatically save all parameters
\& $session\->save_param($form);
\& }
\&
\& # Ensure we have the right sessionid (might be new)
\& $form\->sessionid($session\->id);
\&
\& print $form\->render;
.Ve
.PP
Yes, it's pretty much that easy. See CGI::FormBuilder::Multi for
how to tie this into a multi-page form.
.SH "FREQUENTLY ASKED QUESTIONS (FAQ)"
.IX Header "FREQUENTLY ASKED QUESTIONS (FAQ)"
There are a couple questions and subtle traps that seem to poke people
on a regular basis. Here are some hints.
.SS "I'm confused. Why doesn't this work like CGI.pm?"
.IX Subsection "I'm confused. Why doesn't this work like CGI.pm?"
If you're used to \f(CW\*(C`CGI.pm\*(C'\fR, you have to do a little bit of a brain
shift when working with this module.
.PP
\&\fBFormBuilder\fR is designed to address fields as \fIabstract entities\fR.
That is, you don't create a "checkbox" or "radio group" per se.
Instead, you create a field for the data you want to collect.
The HTML representation is just one property of this field.
.PP
So, if you want a single-option checkbox, simply say something
like this:
.PP
.Vb 2
\& $form\->field(name => \*(Aqjoin_mailing_list\*(Aq,
\& options => [\*(AqYes\*(Aq]);
.Ve
.PP
If you want it to be checked by default, you add the \f(CW\*(C`value\*(C'\fR arg:
.PP
.Vb 3
\& $form\->field(name => \*(Aqjoin_mailing_list\*(Aq,
\& options => [\*(AqYes\*(Aq],
\& value => \*(AqYes\*(Aq);
.Ve
.PP
You see, you're creating a field that has one possible option: "Yes".
Then, you're saying its current value is, in fact, "Yes". This will
result in \fBFormBuilder\fR creating a single-option field (which is
a checkbox by default) and selecting the requested value (meaning
that the box will be checked).
.PP
If you want multiple values, then all you have to do is specify
multiple options:
.PP
.Vb 3
\& $form\->field(name => \*(Aqjoin_mailing_list\*(Aq,
\& options => [\*(AqYes\*(Aq, \*(AqNo\*(Aq],
\& value => \*(AqYes\*(Aq);
.Ve
.PP
Now you'll get a radio group, and "Yes" will be selected for you!
By viewing fields as data entities (instead of HTML tags) you
get much more flexibility and less code maintenance. If you want
to be able to accept multiple values, simply use the \f(CW\*(C`multiple\*(C'\fR arg:
.PP
.Vb 3
\& $form\->field(name => \*(Aqfavorite_colors\*(Aq,
\& options => [qw(red green blue)],
\& multiple => 1);
.Ve
.PP
In all of these examples, to get the data back you just use the
\&\f(CWfield()\fR method:
.PP
.Vb 1
\& my @colors = $form\->field(\*(Aqfavorite_colors\*(Aq);
.Ve
.PP
And the rest is taken care of for you.
.SS "How do I make a multi\-screen/multi\-mode form?"
.IX Subsection "How do I make a multi-screen/multi-mode form?"
This is easily doable, but you have to remember a couple things. Most
importantly, that \fBFormBuilder\fR only knows about those fields you've
told it about. So, let's assume that you're going to use a special
parameter called \f(CW\*(C`mode\*(C'\fR to control the mode of your application so
that you can call it like this:
.PP
.Vb 3
\& myapp.cgi?mode=list&...
\& myapp.cgi?mode=edit&...
\& myapp.cgi?mode=remove&...
.Ve
.PP
And so on. You need to do two things. First, you need the \f(CW\*(C`keepextras\*(C'\fR
option:
.PP
.Vb 1
\& my $form = CGI::FormBuilder\->new(..., keepextras => 1);
.Ve
.PP
This will maintain the \f(CW\*(C`mode\*(C'\fR field as a hidden field across requests
automatically. Second, you need to realize that since the \f(CW\*(C`mode\*(C'\fR is
not a defined field, you have to get it via the \f(CWcgi_param()\fR method:
.PP
.Vb 1
\& my $mode = $form\->cgi_param(\*(Aqmode\*(Aq);
.Ve
.PP
This will allow you to build a large multiscreen application easily,
even integrating it with modules like \f(CW\*(C`CGI::Application\*(C'\fR if you want.
.PP
You can also do this by simply defining \f(CW\*(C`mode\*(C'\fR as a field in your
\&\f(CW\*(C`fields\*(C'\fR declaration. The reason this is discouraged is because
when iterating over your fields you'll get \f(CW\*(C`mode\*(C'\fR, which you likely
don't want (since it's not "real" data).
.SS "Why won't CGI::FormBuilder work with post requests?"
.IX Subsection "Why won't CGI::FormBuilder work with post requests?"
It will, but chances are you're probably doing something like this:
.PP
.Vb 2
\& use CGI qw(:standard);
\& use CGI::FormBuilder;
\&
\& # Our "mode" parameter determines what we do
\& my $mode = param(\*(Aqmode\*(Aq);
\&
\& # Change our form based on our mode
\& if ($mode eq \*(Aqview\*(Aq) {
\& my $form = CGI::FormBuilder\->new(
\& method => \*(Aqpost\*(Aq,
\& fields => [qw(...)],
\& );
\& } elsif ($mode eq \*(Aqedit\*(Aq) {
\& my $form = CGI::FormBuilder\->new(
\& method => \*(Aqpost\*(Aq,
\& fields => [qw(...)],
\& );
\& }
.Ve
.PP
The problem is this: Once you read a \f(CW\*(C`post\*(C'\fR request, it's gone
forever. In the above code, what you're doing is having \f(CW\*(C`CGI.pm\*(C'\fR
read the \f(CW\*(C`post\*(C'\fR request (on the first call of \f(CWparam()\fR).
.PP
Luckily, there is an easy solution. First, you need to modify
your code to use the OO form of \f(CW\*(C`CGI.pm\*(C'\fR. Then, simply specify
the \f(CW\*(C`CGI\*(C'\fR object you create to the \f(CW\*(C`params\*(C'\fR option of \fBFormBuilder\fR:
.PP
.Vb 2
\& use CGI;
\& use CGI::FormBuilder;
\&
\& my $cgi = CGI\->new;
\&
\& # Our "mode" parameter determines what we do
\& my $mode = $cgi\->param(\*(Aqmode\*(Aq);
\&
\& # Change our form based on our mode
\& # Note: since it is post, must specify the \*(Aqparams\*(Aq option
\& if ($mode eq \*(Aqview\*(Aq) {
\& my $form = CGI::FormBuilder\->new(
\& method => \*(Aqpost\*(Aq,
\& fields => [qw(...)],
\& params => $cgi # get CGI params
\& );
\& } elsif ($mode eq \*(Aqedit\*(Aq) {
\& my $form = CGI::FormBuilder\->new(
\& method => \*(Aqpost\*(Aq,
\& fields => [qw(...)],
\& params => $cgi # get CGI params
\& );
\& }
.Ve
.PP
Or, since \fBFormBuilder\fR gives you a \f(CWcgi_param()\fR function, you
could also modify your code so you use \fBFormBuilder\fR exclusively,
as in the previous question.
.SS "How can I change option XXX based on a conditional?"
.IX Subsection "How can I change option XXX based on a conditional?"
To change an option, simply use its accessor at any time:
.PP
.Vb 4
\& my $form = CGI::FormBuilder\->new(
\& method => \*(Aqpost\*(Aq,
\& fields => [qw(name email phone)]
\& );
\&
\& my $mode = $form\->cgi_param(\*(Aqmode\*(Aq);
\&
\& if ($mode eq \*(Aqadd\*(Aq) {
\& $form\->title(\*(AqAdd a new entry\*(Aq);
\& } elsif ($mode eq \*(Aqedit\*(Aq) {
\& $form\->title(\*(AqEdit existing entry\*(Aq);
\&
\& # do something to select existing values
\& my %values = select_values();
\&
\& $form\->values(\e%values);
\& }
\& print $form\->render;
.Ve
.PP
Using the accessors makes permanent changes to your object, so
be aware that if you want to reset something to its original
value later, you'll have to first save it and then reset it:
.PP
.Vb 3
\& my $style = $form\->stylesheet;
\& $form\->stylesheet(0); # turn off
\& $form\->stylesheet($style); # original setting
.Ve
.PP
You can also specify options to \f(CWrender()\fR, although using the
accessors is the preferred way.
.SS "How do I manually override the value of a field?"
.IX Subsection "How do I manually override the value of a field?"
You must specify the \f(CW\*(C`force\*(C'\fR option:
.PP
.Vb 3
\& $form\->field(name => \*(Aqname_of_field\*(Aq,
\& value => $value,
\& force => 1);
.Ve
.PP
If you don't specify \f(CW\*(C`force\*(C'\fR, then the CGI value will always win.
This is because of the stateless nature of the CGI protocol.
.SS "How do I make it so that the values aren't shown in the form?"
.IX Subsection "How do I make it so that the values aren't shown in the form?"
Turn off sticky:
.PP
.Vb 1
\& my $form = CGI::FormBuilder\->new(... sticky => 0);
.Ve
.PP
By turning off the \f(CW\*(C`sticky\*(C'\fR option, you will still be able to access
the values, but they won't show up in the form.
.SS "I can't get ""validate"" to accept my regular expressions!"
.IX Subsection "I can't get ""validate"" to accept my regular expressions!"
You're probably not specifying them within single quotes. See the
section on \f(CW\*(C`validate\*(C'\fR above.
.SS "Can FormBuilder handle file uploads?"
.IX Subsection "Can FormBuilder handle file uploads?"
It sure can, and it's really easy too. Just change the \f(CW\*(C`enctype\*(C'\fR
as an option to \f(CWnew()\fR:
.PP
.Vb 6
\& use CGI::FormBuilder;
\& my $form = CGI::FormBuilder\->new(
\& enctype => \*(Aqmultipart/form\-data\*(Aq,
\& method => \*(Aqpost\*(Aq,
\& fields => [qw(filename)]
\& );
\&
\& $form\->field(name => \*(Aqfilename\*(Aq, type => \*(Aqfile\*(Aq);
.Ve
.PP
And then get to your file the same way as \f(CW\*(C`CGI.pm\*(C'\fR:
.PP
.Vb 2
\& if ($form\->submitted) {
\& my $file = $form\->field(\*(Aqfilename\*(Aq);
\&
\& # save contents in file, etc ...
\& open F, ">$dir/$file" or die $!;
\& while (<$file>) {
\& print F;
\& }
\& close F;
\&
\& print $form\->confirm(header => 1);
\& } else {
\& print $form\->render(header => 1);
\& }
.Ve
.PP
In fact, that's a whole file upload program right there.
.SH REFERENCES
.IX Header "REFERENCES"
This really doesn't belong here, but unfortunately many people are
confused by references in Perl. Don't be \- they're not that tricky.
When you take a reference, you're basically turning something into
a scalar value. Sort of. You have to do this if you want to pass
arrays intact into functions in Perl 5.
.PP
A reference is taken by preceding the variable with a backslash (\e).
In our examples above, you saw something similar to this:
.PP
.Vb 1
\& my @fields = (\*(Aqname\*(Aq, \*(Aqemail\*(Aq); # same as = qw(name email)
\&
\& my $form = CGI::FormBuilder\->new(fields => \e@fields);
.Ve
.PP
Here, \f(CW\*(C`\e@fields\*(C'\fR is a reference. Specifically, it's an array
reference, or "arrayref" for short.
.PP
Similarly, we can do the same thing with hashes:
.PP
.Vb 4
\& my %validate = (
\& name => \*(AqNAME\*(Aq;
\& email => \*(AqEMAIL\*(Aq,
\& );
\&
\& my $form = CGI::FormBuilder\->new( ... validate => \e%validate);
.Ve
.PP
Here, \f(CW\*(C`\e%validate\*(C'\fR is a hash reference, or "hashref".
.PP
Basically, if you don't understand references and are having trouble
wrapping your brain around them, you can try this simple rule: Any time
you're passing an array or hash into a function, you must precede it
with a backslash. Usually that's true for CPAN modules.
.PP
Finally, there are two more types of references: anonymous arrayrefs
and anonymous hashrefs. These are created with \f(CW\*(C`[]\*(C'\fR and \f(CW\*(C`{}\*(C'\fR,
respectively. So, for our purposes there is no real difference between
this code:
.PP
.Vb 2
\& my @fields = qw(name email);
\& my %validate = (name => \*(AqNAME\*(Aq, email => \*(AqEMAIL\*(Aq);
\&
\& my $form = CGI::FormBuilder\->new(
\& fields => \e@fields,
\& validate => \e%validate
\& );
.Ve
.PP
And this code:
.PP
.Vb 4
\& my $form = CGI::FormBuilder\->new(
\& fields => [ qw(name email) ],
\& validate => { name => \*(AqNAME\*(Aq, email => \*(AqEMAIL\*(Aq }
\& );
.Ve
.PP
Except that the latter doesn't require that we first create
\&\f(CW@fields\fR and \f(CW%validate\fR variables.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
.SS FORMBUILDER_DEBUG
.IX Subsection "FORMBUILDER_DEBUG"
This toggles the debug flag, so that you can control FormBuilder
debugging globally. Helpful in mod_perl.
.SH NOTES
.IX Header "NOTES"
Parameters beginning with a leading underscore are reserved for
future use by this module. Use at your own peril.
.PP
The \f(CWfield()\fR method has the alias \f(CWparam()\fR for compatibility
with other modules, allowing you to pass a \f(CW$form\fR around just
like a \f(CW$cgi\fR object.
.PP
The output of the HTML generated natively may change slightly from
release to release. If you need precise control, use a template.
.PP
Every attempt has been made to make this module taint-safe (\-T).
However, due to the way tainting works, you may run into the
message "Insecure dependency" or "Insecure \f(CW$ENV\fR{PATH}". If so,
make sure you are setting \f(CW$ENV{PATH}\fR at the top of your script.
.SH ACKNOWLEDGEMENTS
.IX Header "ACKNOWLEDGEMENTS"
This module has really taken off, thanks to very useful input, bug
reports, and encouraging feedback from a number of people, including:
.PP
.Vb 10
\& Norton Allen
\& Mark Belanger
\& Peter Billam
\& Brad Bowman
\& Jonathan Buhacoff
\& Godfrey Carnegie
\& Jakob Curdes
\& Laurent Dami
\& Bob Egert
\& Peter Eichman
\& Adam Foxson
\& Jorge Gonzalez
\& Florian Helmberger
\& Mark Hedges
\& Mark Houliston
\& Victor Igumnov
\& Robert James Kaes
\& Dimitry Kharitonov
\& Randy Kobes
\& William Large
\& Kevin Lubic
\& Robert Mathews
\& Mehryar
\& Klaas Naajikens
\& Koos Pol
\& Shawn Poulson
\& Victor Porton
\& Dan Collis Puro
\& Wolfgang Radke
\& David Siegal
\& Stephan Springl
\& Ryan Tate
\& John Theus
\& Remi Turboult
\& Andy Wardley
\& Raphael Wegmann
\& Emanuele Zeppieri
.Ve
.PP
Thanks!
.SH "SEE ALSO"
.IX Header "SEE ALSO"
CGI::FormBuilder::Template, CGI::FormBuilder::Messages,
CGI::FormBuilder::Multi, CGI::FormBuilder::Source::File,
CGI::FormBuilder::Field, CGI::FormBuilder::Util,
CGI::FormBuilder::Util, HTML::Template, Text::Template
CGI::FastTemplate
.SH REVISION
.IX Header "REVISION"
\&\f(CW$Id:\fR FormBuilder.pm 65 2006\-09\-07 18:11:43Z nwiger $
.SH AUTHOR
.IX Header "AUTHOR"
Copyright (c) Nate Wiger . All Rights Reserved.
.PP
This module is free software; you may copy this under the terms of
the GNU General Public License, or the Artistic License, copies of
which should have accompanied your Perl kit.