CGI::FormBuilder(3)   User Contributed Perl Documentation  CGI::FormBuilder(3)


NAME
       CGI::FormBuilder - Easily generate and process stateful forms

SYNOPSIS
           use CGI::FormBuilder;

           # Assume we did a DBI query to get existing values
           my $dbval = $sth->fetchrow_hashref;

           # First create our form
           my $form = CGI::FormBuilder->new(
                           name     => 'acctinfo',
                           method   => 'post',
                           stylesheet => '/path/to/style.css',
                           values   => $dbval,   # defaults
                      );

           # Now create form fields, in order
           # FormBuilder will automatically determine the type for you
           $form->field(name => 'fname', label => 'First Name');
           $form->field(name => 'lname', label => 'Last Name');

           # Setup gender field to have options
           $form->field(name => 'gender',
                        options => [qw(Male Female)] );

           # Include validation for the email field
           $form->field(name => 'email',
                        size => 60,
                        validate => 'EMAIL',
                        required => 1);

           # And the (optional) phone field
           $form->field(name => 'phone',
                        size => 10,
                        validate => '/^1?-?\d{3}-?\d{3}-?\d{4}$/',
                        comment  => '<i>optional</i>');

           # Check to see if we're submitted and valid
           if ($form->submitted && $form->validate) {
               # Get form fields as hashref
               my $field = $form->fields;

               # Do something to update your data (you would write this)
               do_data_update($field->{lname}, $field->{fname},
                              $field->{email}, $field->{phone},
                              $field->{gender});

               # Show confirmation screen
               print $form->confirm(header => 1);
           } else {
               # Print out the form
               print $form->render(header => 1);
           }

DESCRIPTION
       If this is your first time using FormBuilder, you should check out the
       website for tutorials and examples at <http://formbuilder.org>.

       You should also consider joining the google group at
       <http://groups.google.com/group/perl-formbuilder>.  There are some
       pretty smart people on the list that can help you out.

   Overview
       I hate generating and processing forms. Hate it, hate it, hate it, hate
       it. My forms almost always end up looking the same, and almost always
       end up doing the same thing. Unfortunately, there haven't really been
       any tools out there that streamline the process. Many modules simply
       substitute Perl for HTML code:

           # The manual way
           print qq(<input name="email" type="text" size="20">);

           # The module way
           print input(-name => 'email', -type => 'text', -size => '20');

       The problem is, that doesn't really gain you anything - you still have
       just as much code. Modules like "CGI.pm" are great for decoding
       parameters, but not for generating and processing whole forms.

       The goal of CGI::FormBuilder (FormBuilder) is to provide an easy way
       for you to generate and process entire CGI form-based applications.
       Its main features are:

       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.

       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.

       Built-in Validation
           Full-blown regex validation for fields, even including JavaScript
           code generation.

       Template Support
           Pluggable support for external template engines, such as
           "HTML::Template", "Text::Template", "Template Toolkit", and
           "CGI::FastTemplate".

       Plus, the native HTML generated is valid XHTML 1.0 Transitional.

   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?
              sortopts   => 'NAME' | 'NUM' | 1 | \&sub,   # sort options?

              # Change size, maxlength, or any other HTML attr
              $htmlattr  => $htmlval,
           );

           # Check for submission
           if ($form->submitted && $form->validate) {

               # Get single value
               my $value = $form->field('name');

               # Get list of fields
               my @field = $form->field;

               # Get hashref of key/value pairs
               my $field = $form->field;
               my $value = $field->{name};

           }

           # Print form
           print $form->render(any_opt_from_new => $some_value);

       That's it. Keep reading.

   Walkthrough
       Let's walk through a whole example to see how FormBuilder works.  We'll
       start with this, which is actually a complete (albeit simple) form
       application:

           use CGI::FormBuilder;

           my @fields = qw(name email password confirm_password zipcode);

           my $form = CGI::FormBuilder->new(
                           fields => \@fields,
                           header => 1
                      );

           print $form->render;

       The above code will render an entire form, and take care of maintaining
       state across submissions. But it doesn't really do anything useful at
       this point.

       So to start, let's add the "validate" option to make sure the data
       entered is valid:

           my $form = CGI::FormBuilder->new(
                           fields   => \@fields,
                           header   => 1,
                           validate => {
                              name  => 'NAME',
                              email => 'EMAIL'
                           }
                      );

       We now get a whole bunch of JavaScript validation code, and the
       appropriate hooks are added so that the form is validated by the
       browser "onsubmit" as well.

       Now, we also want to validate our form on the server side, since the
       user may not be running JavaScript. All we do is add the statement:

           $form->validate;

       Which will go through the form, checking each field specified to the
       "validate" option to see if it's ok. If there's a problem, then that
       field is highlighted, so that when you print it out the errors will be
       apparent.

       Of course, the above returns a truth value, which we should use to see
       if the form was valid. That way, we only update our database if
       everything looks good:

           if ($form->validate) {
               # print confirmation screen
               print $form->confirm;
           } else {
               # print the form for them to fill out
               print $form->render;
           }

       However, we really only want to do this after our form has been
       submitted, since otherwise this will result in our form showing errors
       even though the user hasn't gotten a chance to fill it out yet. As
       such, we want to check for whether the form has been submitted() yet:

           if ($form->submitted && $form->validate) {
               # print confirmation screen
               print $form->confirm;
           } else {
               # print the form for them to fill out
               print $form->render;
           }

       Now that know that our form has been submitted and is valid, we need to
       get our values. To do so, we use the field() method along with the name
       of the field we want:

           my $email = $form->field(name => 'email');

       Note we can just specify the name of the field if it's the only option:

           my $email = $form->field('email');   # same thing

       As a very useful shortcut, we can get all our fields back as a hashref
       of field/value pairs by calling field() with no arguments:

           my $fields = $form->field;      # all fields as hashref

       To make things easy, we'll use this form so that we can pass it easily
       into a sub of our choosing:

           if ($form->submitted && $form->validate) {
               # form was good, let's update database
               my $fields = $form->field;

               # update database (you write this part)
               do_data_update($fields);

               # print confirmation screen
               print $form->confirm;
           }

       Finally, let's say we decide that we like our form fields, but we need
       the HTML to be laid out very precisely. No problem! We simply create an
       "HTML::Template" compatible template and tell FormBuilder to use it.
       Then, in our template, we include a couple special tags which
       FormBuilder will automatically expand:

           <html>
           <head>
           <title><tmpl_var form-title></title>
           <tmpl_var js-head><!-- this holds the JavaScript code -->
           </head>
           <tmpl_var form-start><!-- this holds the initial form tag -->
           <h3>User Information</h3>
           Please fill out the following information:
           <!-- each of these tmpl_var's corresponds to a field -->
           <p>Your full name: <tmpl_var field-name>
           <p>Your email address: <tmpl_var field-email>
           <p>Choose a password: <tmpl_var field-password>
           <p>Please confirm it: <tmpl_var field-confirm_password>
           <p>Your home zipcode: <tmpl_var field-zipcode>
           <p>
           <tmpl_var form-submit><!-- this holds the form submit button -->
           </form><!-- can also use "tmpl_var form-end", same thing -->

       Then, all we need to do add the "template" option, and the rest of the
       code stays the same:

           my $form = CGI::FormBuilder->new(
                           fields   => \@fields,
                           header   => 1,
                           validate => {
                              name  => 'NAME',
                              email => 'EMAIL'
                           },
                           template => 'userinfo.tmpl'
                      );

       So, our complete code thus far looks like this:

           use CGI::FormBuilder;

           my @fields = qw(name email password confirm_password zipcode);

           my $form = CGI::FormBuilder->new(
                           fields   => \@fields,
                           header   => 1,
                           validate => {
                              name  => 'NAME',
                              email => 'EMAIL'
                           },
                           template => 'userinfo.tmpl',
                      );

           if ($form->submitted && $form->validate) {
               # form was good, let's 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;
           }

       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.

       Note: If you are confused at all by the backslashes you see in front of
       some data pieces above, such as "\@fields", skip down to the brief
       section entitled "REFERENCES" at the bottom of this document (it's
       short).

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:

           www.formbuilder.org

       And click on "Tutorials" and "Examples". Then, use the following
       section as a reference later on.

   new()
       This method creates a new $form 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:

           my $form = CGI::FormBuilder->new(
                           fields => [qw(first_name birthday favorite_car)]
                      );

       As of 3.02:

           my $form = CGI::FormBuilder->new(
                           source => 'myform.conf'   # form and field options
                      );

       For details on the external file format, see
       CGI::FormBuilder::Source::File.

       Any of the options below, in addition to being specified to new(), can
       also be manipulated directly with a method of the same name. For
       example, to change the "header" and "stylesheet" options, either of
       these works:

           # Way 1
           my $form = CGI::FormBuilder->new(
                           fields => \@fields,
                           header => 1,
                           stylesheet => '/path/to/style.css',
                      );

           # Way 2
           my $form = CGI::FormBuilder->new(
                           fields => \@fields
                      );
           $form->header(1);
           $form->stylesheet('/path/to/style.css');

       The second form is useful if you want to wrap certain options in
       conditionals:

           if ($have_template) {
               $form->header(0);
               $form->template('template.tmpl');
           } else {
               $form->header(1);
               $form->stylesheet('/path/to/style.css');
           }

       The following is a description of each option, in alphabetical order:

       action => $script
           What script to point the form to. Defaults to itself, which is the
           recommended setting.

       body => \%attr
           This takes a hashref of attributes that will be stuck in the
           "<body>" tag verbatim (for example, bgcolor, alink, etc).  See the
           "fieldattr" tag for more details, and also the "template" option.

       charset
           This forcibly overrides the charset. Better handled by loading an
           appropriate "messages" module, which will set this for you.  See
           CGI::FormBuilder::Messages for more details.

       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.

       fields => \@array | \%hash
           As shown above, the "fields" 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 the central option to FormBuilder.

           You can also specify a hashref of key/value pairs. The advantage is
           you can then bypass the "values" 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 "fields" is not very useful.

       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
           field() method.

       fieldattr => \%attr
           This option allows you to specify any HTML attribute and have it be
           the default for all fields. This used to be good for stylesheets,
           but now that there is a "stylesheet" option, this is fairly
           useless.

       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.

           To use fieldsets, specify an arrayref of "<fieldset>" names:

               fieldsets => [qw(account preferences contacts)]

           You can get a different "<legend>" tag if you specify a nested
           arrayref:

               fieldsets => [
                   [ account  => 'Account Information' ],
                   [ preferences => 'Website Preferences' ],
                   [ contacts => 'Email and Phone Numbers' ],
               ]

           If you're using the source file, that looks like this:

               fieldsets: account=Account Information,preferences=...

           Then, for each field, specify which fieldset it belongs to:

               $form->field(name => 'first_name', fieldset => 'account');
               $form->field(name => 'last_name',  fieldset => 'account');
               $form->field(name => 'email_me',   fieldset => 'preferences');
               $form->field(name => 'home_phone', fieldset => 'contacts');
               $form->field(name => 'work_phone', fieldset => 'contacts');

           You can also automatically create a new "fieldset" on the fly by
           specifying a new one:

               $form->field(name => 'remember_me', fieldset => 'advanced');

           To set the "<legend>" in this case, you have two options.  First,
           you can just choose a more readable "fieldset" name:

               $form->field(name => 'remember_me',
                            fieldset => 'Advanced');

           Or, you can change the name using the "fieldset" accessor:

               $form->fieldset(advanced => 'Advanced Options');

           Note that fieldsets without fields are silently ignored, so you can
           also just specify a huge list of possible fieldsets to new(), and
           then only add fields as you need them.

       fieldsubs => 0 | 1
           This allows autoloading of field names so you can directly access
           them as:

               $form->$fieldname(opt => 'val');

           Instead of:

               $form->field(name => $fieldname, opt => 'val');

           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.

       font => $font | \%attr
           The font face to use for the form. This is output as a series of
           "<font>" 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 "<font>" tag:

               font => {face => 'verdana', size => '-1', color => 'gray'}

           The above becomes:

               <font face="verdana" size="-1" color="gray">

           I used to use this all the time, but the "stylesheet" option is SO
           MUCH BETTER. Trust me, take a day and learn the basics of CSS, it's
           totally worth it.

       header => 0 | 1
           If set to 1, a valid "Content-type" header will be printed out,
           along with a whole bunch of HTML "<body>" code, a "<title>" tag,
           and so on. This defaults to 0, since often people end up using
           templates or embedding forms in other HTML.

       javascript => 0 | 1
           If set to 1, JavaScript is generated in addition to HTML, the
           default setting.

       jserror => 'function_name'
           If specified, this will get called instead of the standard JS
           alert() function on error. The function signature is:

               function_name(form, invalid, alertstr, invalid_fields)

           The function can be named anything you like. A simple one might
           look like this:

               my $form = CGI::FormBuilder->new(
                   jserror => 'field_errors',
                   jshead => <<'EOJS',
           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 = 'normal_field';
               }
               // 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 = 'invalid_field';
               }
               alert(alertstr);
               return false;
           }
           EOJS
               );

           Note that it should return false to prevent form submission.

           This can be used in conjunction with "jsfunc", which can add
           additional manual validations before "jserror" is called.

       jsfunc => $jscode
           This is verbatim JavaScript that will go into the "validate"
           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:

               1. append to the JavaScript string "alertstr"
               2. increment the JavaScript number "invalid"

           For example:

               my $jsfunc = <<'EOJS';   # note single quote (see Hint)
                 if (form.password.value == 'password') {
                   alertstr += "Moron, you can't use 'password' for your password!\\n";
                   invalid++;
                 }
               EOJS

               my $form = CGI::FormBuilder->new(... jsfunc => $jsfunc);

           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 "form._submit.value":

               my $jsfunc = <<'EOJS';   # note single quotes (see Hint)
                 if (form._submit.value == 'Delete') {
                    if (confirm("Really DELETE this entry?")) return true;
                    return false;
                 } else if (form._submit.value == 'Cancel') {
                    // skip validation since we're cancelling
                    return true;
                 }
               EOJS

           Hint: To prevent accidental expansion of embedding strings and
           escapes, you should put your "HERE" string in single quotes, as
           shown above.

       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.

       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 cgi_param(), NOT field(), to access the values.

           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 "mode" and "company". Again, to
           access them:

               my $mode = $form->cgi_param('mode');
               $form->cgi_param(name => 'mode', value => 'relogin');

           See "CGI.pm" for details on param() usage.

       labels => \%hash
           Like "values", this is a list of key/value pairs where the keys are
           the names of "fields" specified above. By default, 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.

       lalign => 'left' | 'right' | 'center'
           A legacy shortcut for:

               th => { align => 'left' }

           Even better, use the "stylesheet" option and tweak the ".fb_label"
           class. Either way, don't use this.

       lang
           This forcibly overrides the lang. Better handled by loading an
           appropriate "messages" module, which will set this for you.  See
           CGI::FormBuilder::Messages for more details.

       method => 'post' | 'get'
           The type of CGI method to use, either "post" or "get". Defaults to
           "get" if nothing is specified. Note that for forms that cause
           changes on the server, such as database inserts, you should use the
           "post" method.

       messages => 'auto' | $file | \%hash | $locale
           This option overrides the default 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
           CGI::FormBuilder::Messages.

       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 "<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.

       options => \%hash
           This is one of several 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 field() for the "department" and
           "in_stock" fields to set options individually.

       params => $object
           This specifies an object from which the parameters should be
           derived.  The object must have a 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 "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 "CGI.pm" object separately and are
           using a "post" form method:

               use CGI;
               use CGI::FormBuilder;

               my $q = new CGI;
               my $form = CGI::FormBuilder->new(... params => $q);

           Usually you don't need to do this, unless you need to access other
           parameters outside of FormBuilder's control.

       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 "required"
           option is not specified, by default any fields named in "validate"
           will be required.

           In addition, the "required" option also takes two other settings,
           the strings "ALL" and "NONE". If you specify "ALL", then all fields
           are required. If you specify "NONE", then none of them are in spite
           of what may be set via the "validate" option.

           This is useful if you have fields that are optional, but that you
           want to be validated if filled in:

               my $form = CGI::FormBuilder->new(
                               fields => qw[/name email/],
                               validate => { email => 'EMAIL' },
                               required => 'NONE'
                          );

           This would make the "email" field optional, but if filled in then
           it would have to match the "EMAIL" pattern.

           In addition, it is very important to note that if the "required"
           and "validate" options are specified, then they are taken as an
           intersection. That is, only those fields specified as "required"
           must be filled in, and the rest are optional. For example:

               my $form = CGI::FormBuilder->new(
                               fields => qw[/name email/],
                               validate => { email => 'EMAIL' },
                               required => [qw(name)]
                          );

           This would make the "name" field mandatory, but the "email" field
           optional. However, if "email" is filled in, then it must match the
           builtin "EMAIL" pattern.

       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".

       selectnum => $threshold
           This detects how FormBuilder's auto-type generation works. If a
           given field has options, then it will be a radio group by default.
           However, if more than "selectnum" options are present, then it will
           become a select list. The default is 5 or more options. For
           example:

               # This will be a radio group
               my @opt = qw(Yes No);
               $form->field(name => 'answer', options => \@opt);

               # However, this will be a select list
               my @states = qw(AK CA FL NY TX);
               $form->field(name => 'state', options => \@states);

               # Single items are checkboxes (allows unselect)
               $form->field(name => 'answer', options => ['Yes']);

           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 "multiple" option is specified and
           the field has less than "selectnum" options. Got it?

       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 "smartness" to
           0. If you want it to be really smart, like figuring out what type
           of validation routines to use for you, set it to 2. It defaults to
           1.

       sortopts => BUILTIN | 1 | \&sub
           If specified to new(), this has the same effect as the same-named
           option to field(), only it applies to all fields.

       source => $filename
           You can use this option to initialize FormBuilder 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.

       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.

       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.

       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:

               print $form->render(submit => 'Do Lookup');

           Would make it so the submit button says "Do Lookup" on it.

           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:

               print $form->render(submit => ['Add A Gift', 'No Thank You']);

           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 submitted() function:

               my $clicked = $form->submitted;

           So if the user clicked "Add A Gift" then that is what would end up
           in the variable $clicked above. This allows nice conditionality:

               if ($form->submitted eq 'Add A Gift') {
                   # show the gift selection screen
               } elsif ($form->submitted eq 'No Thank You')
                   # just process the form
               }

           See the "EXAMPLES" section for more details.

       styleclass => $string
           The string to use as the "style" name, if the following option is
           enabled.

       stylesheet => 0 | 1 | $path
           This option turns on stylesheets in the HTML output by FormBuilder.
           Each element is printed with the "class" of "styleclass" ("fb" by
           default). It is up to you to provide the actual style definitions.
           If you provide a $path rather than just a 1/0 toggle, then that
           $path will be included in a "<link>" tag as well.

           The following tags are created by this option:

               ${styleclass}           top-level table/form class
               ${styleclass}_required  labels for fields that are required
               ${styleclass}_invalid   any fields that failed validate()

           If you're contemplating stylesheets, the best thing is to just turn
           this option on, then see what's spit out.

           See the section on "STYLESHEETS" for more details on FormBuilder
           style sheets.

       table => 0 | 1 | \%tabletags
           By default FormBuilder decides how to layout the form based on the
           number of fields, values, etc. You can force it into a table by
           specifying 1, or force it out of one with 0.

           If you specify a hashref instead, then these will be used to create
           the "<table>" tag. For example, to create a table with no
           cellpadding or cellspacing, use:

               table => {cellpadding => 0, cellspacing => 0}

           Also, you can specify options to the "<td>" and "<tr>" elements as
           well in the same fashion.

       template => $filename | \%hash | \&sub | $object
           This points to a filename that contains an "HTML::Template"
           compatible template to use to layout the HTML. You can also specify
           the "template" option as a reference to a hash, allowing you to
           further customize the template processing options, or use other
           template engines.

           If "template" points to a sub reference, that routine is called and
           its return value directly returned. If it is an object, then that
           object's render() routine is called and its value returned.

           For lots more information, please see CGI::FormBuilder::Template.

       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 $adm
           for more help", but if you want lots of text check out the
           "template" option above.

       title => $title
           This takes a string to use as the title of the form.

       values => \%hash | \@array
           The "values" 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).

           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:

               my $rec = $sth->fetchrow_hashref;
               my $form = CGI::FormBuilder->new(fields => \@fields,
                                                values => $rec);

           You can also pass an arrayref, in which case each value is used
           sequentially for each field as specified to the "fields" option.

       validate => \%hash | $object
           This option takes either a hashref of key/value pairs or a
           Data::FormValidator object.

           In the case of the hashref, each key is the name of a field from
           the "fields" option, or the string "ALL" in which case it applies
           to all fields. Each value is one of the following:

               - a regular expression in 'quotes' 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)

           In addition, each of these can also be grouped together as:

               - a hashref containing pairings of comparisons to do for
                 the two different languages, "javascript" and "perl"

           By default, the "validate" option also toggles each field to make
           it required. However, you can use the "required" option to change
           this, see it for more details.

           Let's look at a concrete example.  Note that the javascript
           validation is a negative match, while the perl validation is a
           positive match.

               my $form = CGI::FormBuilder->new(
                   fields => [qw(
                       username    password    confirm_password
                       first_name  last_name   email
                   )],
                   validate => {
                       username   => [qw(nate jim bob)],
                       first_name => '/^\w+$/',    # note the
                       last_name  => '/^\w+$/',    # single quotes!
                       email      => 'EMAIL',
                       password   => \&check_password,
                       confirm_password => {
                           javascript => '!= form.password.value',       # neg
                           perl       => 'eq $form->field("password")',  # 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
               }

           This would create both JavaScript and Perl routines on the fly that
           would ensure:

               - "username" was either "nate", "jim", or "bob"
               - "first_name" and "last_name" both match the regex's 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

           Any regular expressions you specify must be enclosed in single
           quotes because they need to be used in both JavaScript and Perl
           code. As such, specifying a "qr//" will NOT work.

           Note that for both the "javascript" and "perl" hashref code
           options, the form will be present as the variable named "form". For
           the Perl code, you actually get a complete $form object meaning
           that you have full access to all its methods (although the field()
           method is probably the only one you'll need for validation).

           In addition to taking any regular expression you'd like, the
           "validate" option also has many builtin defaults that can prove
           helpful:

               VALUE   -  is any type of non-null value
               WORD    -  is a word (\w+)
               NAME    -  matches [a-zA-Z] only
               FNAME   -  person's first name, like "Jim" or "Joe-Bob"
               LNAME   -  person's 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 -'s
               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:\windows\system)
               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

           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.

           You can also pass a Data::FormValidator object as the value of
           "validate".  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 "required" option to new() is ignored, since you should be
           setting the required fields through your FormValidator profile.

           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 validate().

           Note that currently, doing validation through a FormValidator
           object doesn't generate any JavaScript validation code for you.

       Note that any other options specified are passed to the "<form>" tag
       verbatim. For example, you could specify "onsubmit" or "enctype" to add
       the respective attributes.

   prepare()
       This function prepares a form for rendering. It is automatically called
       by render(), but calling it yourself may be useful if you are using
       Catalyst or some other large framework. It returns the same hash that
       will be used by render():

           my %expanded = $form->prepare;

       You could use this to, say, tweak some custom values and then pass it
       to your own rendering object.

   render()
       This function renders the form into HTML, and returns a string
       containing the form. The most common use is simply:

           print $form->render;

       You can also supply options to render(), just like you had called the
       accessor functions individually. These two uses are equivalent:

           # this code:
           $form->header(1);
           $form->stylesheet('style.css');
           print $form->render;

           # is the same as:
           print $form->render(header => 1,
                               stylesheet => 'style.css');

       Note that both forms make permanent changes to the underlying object.
       So the next call to render() will still have the header and stylesheet
       options in either case.

   field()
       This method is used to both get at field values:

           my $bday = $form->field('birthday');

       As well as make changes to their attributes:

           $form->field(name  => 'fname',
                        label => "First Name");

       A very common use is to specify a list of options and/or the field
       type:

           $form->field(name    => 'state',
                        type    => 'select',
                        options => \@states);      # you supply @states

       In addition, when you call field() without any arguments, it returns a
       list of valid field names in an array context:

           my @fields = $form->field;

       And a hashref of field/value pairs in scalar context:

           my $fields = $form->field;
           my $name = $fields->{name};

       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:

           $form->field(name => 'color', options => \@colors,
                        multiple => 1);        # allow multi-select

       Then you will only get one value for "color" in the hashref. In this
       case you'll need to access it via field() to get them all:

           my @colors = $form->field('color');

       The "name" option is described first, and the remaining options are in
       order:

       name => $name
           The field to manipulate. The "name =>" part is optional if it's the
           only argument. For example:

               my $email = $form->field(name => 'email');
               my $email = $form->field('email');   # same thing

           However, if you're specifying more than one argument, then you must
           include the "name" part:

               $form->field(name => 'email', size => '40');

       add_after_option => $html
           Adds the specified HTML code after each checkbox (or radio) option.

       add_before_option => $html
           Adds the specified HTML code before each checkbox (or radio)
           option.

       columns => 0 | $width
           If set and the field is of type 'checkbox' or 'radio', then the
           options will be wrapped at the given width.

       comment => $string
           This prints out the given comment after the field. A good use of
           this is for additional help on what the field should contain:

               $form->field(name    => 'dob',
                            label   => 'D.O.B.',
                            comment => 'in the format MM/DD/YY');

           The above would yield something like this:

               D.O.B. [____________] in the format MM/DD/YY

           The comment is rendered verbatim, meaning you can use HTML links or
           code in it if you want.

       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.

       cookies => 0 | 1
           Controls whether to generate a cookie if "sessionid" has been set.
           This also requires that "header" be set as well, since the cookie
           is wrapped in the header. Defaults to 1, meaning it will
           automatically work if you turn on "header".

       force => 0 | 1
           This is used in conjunction with the "value" option to forcibly
           override a field's value. See below under the "value" option for
           more details. For compatibility with "CGI.pm", you can also call
           this option "override" instead, but don't tell anyone.

       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
           "text" and "file" field types.

           If you set "growable" 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 $limit 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.

       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 "select" to "radio" or "checkbox", then the
           action changes from "onchange" to "onclick". Why?!?!

           So if you said:

               $form->field(name    => 'credit_card',
                            options => \@cards,
                            jsclick => 'recalc_total();');

           This would generate the following code, depending on the number of
           @cards:

               <select name="credit_card" onchange="recalc_total();"> ...

               <radio name="credit_card" onclick="recalc_total();"> ...

           You get the idea.

       jsmessage => $string
           You can use this to specify your own custom message for the field,
           which will be printed if it fails validation. The "jsmessage"
           option affects the JavaScript popup box, and the "message" option
           affects what is printed out if the server-side validation fails.
           If "message" is specified but not "jsmessage", then "message" will
           be used for JavaScript as well.

               $form->field(name      => 'cc',
                            label     => 'Credit Card',
                            message   => 'Invalid credit card number',
                            jsmessage => 'The card number in "%s" is invalid');

           The %s will be filled in with the field's "label".

       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.

       labels => \%hash
           This option to field() is outdated. You can get the same effect by
           passing data structures directly to the "options" argument (see
           below).  If you have well-named data, check out the "nameopts"
           option.

           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:

               $form->field(name    => 'state',
                            options => [qw(AZ CA NV OR WA)],
                            labels  => {
                                 AZ => 'Arizona',
                                 CA => 'California',
                                 NV => 'Nevada',
                                 OR => 'Oregon',
                                 WA => 'Washington
                            });

           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:

               $form->field(name    => 'state',
                            options => [
                               [ AZ => 'Arizona' ],
                               [ CA => 'California' ],
                               [ NV => 'Nevada' ],
                               [ OR => 'Oregon' ],
                               [ WA => 'Washington ],
                            ]);

           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 "options" arg.

       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.

       message => $string
           Like "jsmessage", this customizes the output error string if
           server-side validation fails for the field. The "message" option
           will also be used for JavaScript messages if it is specified but
           "jsmessage" is not. See above under "jsmessage" for details.

       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.

       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:

               $form->field(name     => 'department',
                            options  => qw[(molecular_biology
                                            philosophy psychology
                                            particle_physics
                                            social_anthropology)],
                            nameopts => 1);

           This would create a list like:

               <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>

           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 "options" data structures if your data
           is regular enough to support it.

       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:

               $form->field(name    => 'vote_for_president',
                            options => [qw(Bush Kerry)],
                            other   => 1);

           That would generate HTML somewhat like this:

               Vote For President:  [ ] Bush [ ] Kerry [ ] Other: [______]

           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.

       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 "type" parameter:

               $form->field(name => 'opinion',
                            options => [qw(yes no maybe so)]);

           From that, you will get something like this:

               <select name="opinion">
               <option value="yes">yes</option>
               <option value="no">no</option>
               <option value="maybe">maybe</option>
               <option value="so">so</option>
               </select>

           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:

               push @opt, ['yes', 'You betcha!'];
               push @opt, ['no', 'No way Jose'];
               push @opt, ['maybe', 'Perchance...'];
               push @opt, ['so', 'So'];
               $form->field(name => 'opinion', options => \@opt);

           Would result in something like the following:

               <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>

           And this code would have the same effect:

               push @opt, { yes => 'You betcha!' };
               push @opt, { no  => 'No way Jose' };
               push @opt, { maybe => 'Perchance...' };
               push @opt, { so  => 'So' };
               $form->field(name => 'opinion', options => \@opt);

           Finally, you can specify a "\&sub" which must return either an
           "\@arrayref" or "\%hashref" of data, which is then expanded using
           the same algorithm.

       optgroups => 0 | 1 | \%hashref
           If "optgroups" is specified for a field ("select" fields only),
           then the above "options" array is parsed so that the third argument
           is taken as the name of the optgroup, and an "<optgroup>" tag is
           generated appropriately.

           An example will make this behavior immediately obvious:

             my $opts = $dbh->selectall_arrayref(
                           "select id, name, category from software
                            order by category, name"
                         );

             $form->field(name => 'software_title',
                          options => $opts,
                          optgroups => 1);

           The "optgroups" setting would then parse the third element of $opts
           so that you'd get an "optgroup" every time that "category" changed:

             <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>

           In addition, if "optgroups" 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 "category_id" in the "software" table.  You
           could provide an "optgroups" hash like:

               my %optgroups = (
                   1   =>  'antivirus',
                   2   =>  'office',
                   3   =>  'misc',
               );
               $form->field(..., optgroups => \%optgroups);

           Note: No attempt is made by FormBuilder to properly sort your
           option optgroups - it is up to you to provide them in a sensible
           order.

       required => 0 | 1
           If set to 1, the field must be filled in:

               $form->field(name => 'email', required => 1);

           This is rarely useful - what you probably want are the "validate"
           and "required" options to new().

       selectname => 0 | 1 | $string
           By default, this is set to 1 and any single-select lists are
           prefixed by the message "form_select_default" ("-select-" for
           English). If set to 0, then this string is not prefixed.  If set to
           a $string, then that string is used explicitly.

           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 "value"
           option to specify the default value.

       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
           "BUILTIN" setting:

               NAME            Sort option values by name
               NUM             Sort option values numerically
               LABELNAME       Sort option labels by name
               LABELNUM        Sort option labels numerically

           For example:

               $form->field(name => 'category',
                            options => \@cats,
                            sortopts => 'NAME');

           Would sort the @cats options in alphabetic ("NAME") order.  The
           option "NUM" would sort them in numeric order. If you specify "1",
           then an alphabetic sort is done, just like the default Perl sort.

           In addition, you can specify a sub reference which takes pairs of
           values to compare and returns the appropriate return value that
           Perl sort() expects.

       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.

           By default, the type is automatically determined by FormBuilder
           based on the following algorithm:

               Field options?
                   No = text (done)
                   Yes:
                       Less than 'selectnum' setting?
                           No = select (done)
                           Yes:
                               Is the 'multiple' option set?
                               Yes = checkbox (done)
                               No:
                                   Have just one single option?
                                       Yes = checkbox (done)
                                       No = radio (done)

           I recommend you let FormBuilder do this for you in most cases, and
           only tweak those you really need to.

       value => $value | \@values
           The "value" 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.

           If a CGI value is present it will always win. To forcibly change a
           value, you need to specify the "force" option:

               # Example that hides credit card on confirm screen
               if ($form->submitted && $form->validate) {
                   my $val = $form->field;

                   # hide CC number
                   $form->field(name => 'credit_card',
                                value => '(not shown)',
                                force => 1);

                   print $form->confirm;
               }

           This would print out the string "(not shown)" on the confirm()
           screen instead of the actual number.

       validate => '/regex/'
           Similar to the "validate" option used in new(), this affects the
           validation just of that single field. As such, rather than a
           hashref, you would just specify the regex to match against.

           This regex must be specified as a single-quoted string, and NOT as
           a qr// regex. The reason for this is it needs to be usable by the
           JavaScript routines as well.

       $htmlattr => $htmlval
           In addition to the above tags, the field() 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:

               $form->field(name => 'email', class => 'FormField',
                            size => 80);

           Then when you call "$form-"render> you would get a field something
           like this:

               <input type="text" name="email" class="FormField" size="80">

           (Of course, for this to really work you still have to create a
           class called "FormField" in your stylesheet.)

           See also the "fieldattr" option which provides global attributes to
           all fields.

   cgi_param()
       The above field() method will only return fields which you have
       explicitly defined in your form. Excess parameters will be silently
       ignored, to help ensure users can't mess with your form.

       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:

           http://hr-outsourcing.com/newuser.cgi?company=mr_propane

       This could change your page's HTML so that it displayed the appropriate
       company name and logo, without polluting your form parameters.

       This call simply redispatches to "CGI.pm"'s param() method, so consult
       those docs for more information.

   tmpl_param()
       This allows you to manipulate template parameters directly.  Extending
       the above example:

           my $form = CGI::FormBuilder->new(template => 'some.tmpl');

           my $company = $form->cgi_param('company');
           $form->tmpl_param(company => $company);

       Then, in your template:

           Hello, <tmpl_var company> employee!
           <p>
           Please fill out this form:
           <tmpl_var form-start>
           <!-- etc... -->

       For really precise template control, you can actually create your own
       template object and then pass it directly to FormBuilder.  See
       CGI::FormBuilder::Template for more details.

   sessionid()
       This gets and sets the sessionid, which is stored in the special form
       field "_sessionid". 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 "CGI::Session".

       Since you can set the session id via the "_sessionid" field, you can
       pass it as an argument when first showing the form:

           http://mydomain.com/forms/update_info.cgi?_sessionid=0123-091231

       This would set things up so that if you called:

           my $id = $form->sessionid;

       This would get the value "0123-091231" in your script. Conversely, if
       you generate a new sessionid on your own, and wish to include it
       automatically, simply set is as follows:

           $form->sessionid($id);

       If the sessionid is set, and "header" is set, then FormBuilder will
       also automatically generate a cookie for you.

       See "EXAMPLES" for "CGI::Session" example.

   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:

           if ($form->submitted) { ... }

       Or to retrieve the button that was actually clicked on in the case of
       multiple submit buttons:

           if ($form->submitted eq 'Update') {
               ...
           } elsif ($form->submitted eq 'Delete') {
               ...
           }

       It's best to call validate() 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 "name" option described
       above.

       If you're writing a multiple-form app, you should name your forms with
       the "name" option to ensure that you are getting an accurate return
       value from this sub. See the "name" option above, under render().

       You can also specify the name of an optional field which you want to
       "watch" instead of the default "_submitted" 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:

           mysearch.cgi?lookup=what+to+look+for

       Normally, submitted() would return false since the "_submitted" field
       is not included. However, you can override this by saying:

           $form->submitted('lookup');

       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.)

   validate()
       This validates the form based on the validation criteria passed into
       new() via the "validate" option. In addition, you can specify
       additional criteria to check that will be valid for just that call of
       validate(). This is useful is you have to deal with different geos:

           if ($location eq 'US') {
               $form->validate(state => 'STATE', zipcode => 'ZIPCODE');
           } else {
               $form->validate(state => '/^\w{2,3}$/');
           }

       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.

       Note that if you pass args to your validate() 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 "validate" option to the new() function, and just call the
       validate() function with no arguments.

   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 render(),
       twiddling a couple options.

       If you're using templates, you probably want to specify a separate
       success template, such as:

           if ($form->submitted && $form->validate) {
               print $form->confirm(template => 'success.tmpl');
           } else {
               print $form->render(template => 'fillin.tmpl');
           }

       So that you don't get the same screen twice.

   mailconfirm()
       This sends a confirmation email to the named addresses. The "to"
       argument is required; everything else is optional. If no "from" is
       specified then it will be set to the address "auto-reply" since that is
       a common quasi-standard in the web app world.

       This does not send any of the form results. Rather, it simply prints
       out a message saying the submission was received.

   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:

           name: Nate Wiger
           email: nate@wiger.org
           colors: red green blue

       And so on. You can change this by specifying the "delimiter" and
       "joiner" options. For example this:

           $form->mailresults(to => $to, delimiter => '=', joiner => ',');

       Would produce an email like this:

           name=Nate Wiger
           email=nate@wiger.org
           colors=red,green,blue

       Note that now the last field ("colors") is separated by commas since
       you have multiple values and you specified a comma as your "joiner".

   mailresults() with plugin
       Now you can also specify a plugin to use with mailresults, in the
       namespace "CGI::FormBuilder::Mail::*".  These plugins may depend on
       other libraries.  For example, this:

           $form->mailresults(
               plugin          => 'FormatMultiPart',
               from            => 'Mark Hedges <hedges@ucsd.edu>',
               to              => 'Nate Wiger <nwiger@gmail.com>',
               smtp            => $smtp_host_or_ip,
               format          => 'plain',
           );

       will send your mail formatted nicely in text using "Text::FormatTable".
       (And if you used format => 'html' it would use "HTML::QuickTable".)

       This particular plugin uses "MIME::Lite" and "Net::SMTP" to communicate
       directly with the SMTP server, and does not rely on a shell escape.
       See CGI::FormBuilder::Mail::FormatMultiPart for more information.

       This establishes a simple mail plugin implementation standard for your
       own mailresults() plugins.  The plugin should reside under the
       "CGI::FormBuilder::Mail::*" namespace. It should have a constructor
       new() which accepts a hash-as-array of named arg parameters, including
       form => $form.  It should have a mailresults() object method that does
       the right thing.  It should use "CGI::FormBuilder::Util" and puke() if
       something goes wrong.

       Calling $form->mailresults( plugin => 'Foo', ... ) will load
       "CGI::FormBuilder::Mail::Foo" and will pass the FormBuilder object as a
       named param 'form' with all other parameters passed intact.

       If it should croak, confess, die or otherwise break if something goes
       wrong, FormBuilder.pm will warn any errors and the built-in
       mailresults() method will still try.

   mail()
       This is a more generic version of the above; it sends whatever is given
       as the "text" argument via email verbatim to the "to" address.  In
       addition, if you're not running "sendmail" you can specify the "mailer"
       parameter to give the path of your mailer. This option is accepted by
       the above functions as well.

COMPATIBILITY
       The following methods are provided to make FormBuilder behave more like
       other modules, when desired.

   header()
       Returns a "CGI.pm" header, but only if "header => 1" is set.

   param()
       This is an alias for field(), provided for compatibility. However,
       while field() does act "compliantly" for easy use in "CGI::Session",
       "Apache::Request", etc, it is not 100% the same. As such, I recommend
       you use field() in your code, and let receiving objects figure the
       param() thing out when needed:

           my $sess = CGI::Session->new(...);
           $sess->save_param($form);   # will see param()

   query_string()
       This returns a query string similar to "CGI.pm", but ONLY containing
       form fields and any "keepextras", if specified. Other params are
       ignored.

   self_url()
       This returns a self url, similar to "CGI.pm", but again ONLY with form
       fields.

   script_name()
       An alias for "$form->action".

STYLESHEETS (CSS)
       If the "stylesheet" option is enabled (by setting it to 1 or the path
       of a CSS file), then FormBuilder will automatically output style
       classes for every single form element:

           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

       Here's a simple example that you can put in "fb.css" which spruces up a
       couple basic form features:

           /* 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;
           }

       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.

EXAMPLES
       I find this module incredibly useful, so here are even more examples,
       pasted from sample code that I've written:

   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.

           #!/usr/bin/perl

           use strict;
           use CGI::FormBuilder;

           my @states = my_state_list();   # you write this

           my $form = CGI::FormBuilder->new(
                           method => 'post',
                           fields => [
                               qw(first_name last_name
                                  email send_me_emails
                                  address state zipcode
                                  credit_card expiration)
                           ],

                           header => 1,
                           title  => 'Finalize Your Order',
                           submit => ['Place Order', 'Cancel'],
                           reset  => 0,

                           validate => {
                                email   => 'EMAIL',
                                zipcode => 'ZIPCODE',
                                credit_card => 'CARD',
                                expiration  => 'MMYY',
                           },
                           required => 'ALL',
                           jsfunc => <<EOJS,
           // skip js validation if they clicked "Cancel"
           if (this._submit.value == 'Cancel') return true;
       EOJS
                      );

           # Provide a list of states
           $form->field(name    => 'state',
                        options => \@states,
                        sortopts=> 'NAME');

           # Options for mailing list
           $form->field(name    => 'send_me_emails',
                        options => [[1 => 'Yes'], [0 => 'No']],
                        value   => 0);   # "No"

           # Check for valid order
           if ($form->submitted eq 'Cancel') {
               # redirect them to the homepage
               print $form->cgi->redirect('/');
               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;
           }

       This will create a form called "Finalize Your Order" that will provide
       a pulldown menu for the "state", a radio group for "send_me_emails",
       and normal text boxes for the rest. It will then validate all the
       fields, using specific patterns for those fields specified to
       "validate".

   Ex2: order_form.cgi
       Here's an example that adds some fields dynamically, and uses the
       "debug" option spit out gook:

           #!/usr/bin/perl

           use strict;
           use CGI::FormBuilder;

           my $form = CGI::FormBuilder->new(
                           method => 'post',
                           fields => [
                               qw(first_name last_name email
                                  address state zipcode)
                           ],
                           header => 1,
                           debug  => 2,    # gook
                           required => 'NONE',
                      );

           # This adds on the 'details' field to our form dynamically
           $form->field(name => 'details',
                        type => 'textarea',
                        cols => '50',
                        rows => '10');

           # And this adds user_name with validation
           $form->field(name  => 'user_name',
                        value => $ENV{REMOTE_USER},
                        validate => 'NAME');

           if ($form->submitted && $form->validate) {
               # ... more code goes here to do stuff ...
               print $form->confirm;
           } else {
               print $form->render;
           }

       In this case, none of the fields are required, but the "user_name"
       field will still be validated if filled in.

   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.

           #!/usr/bin/perl

           use strict;
           use CGI::FormBuilder;

           my $form = CGI::FormBuilder->new(
                           fields => [qw(type string status category)],
                           header => 1,
                           template => 'ticket_search.tmpl',
                           submit => 'Search',     # search button
                           reset  => 0,            # and no reset
                      );

           # Need to setup some specific field options
           $form->field(name    => 'type',
                        options => [qw(ticket requestor hostname sysadmin)]);

           $form->field(name    => 'status',
                        type    => 'radio',
                        options => [qw(incomplete recently_completed all)],
                        value   => 'incomplete');

           $form->field(name    => 'category',
                        type    => 'checkbox',
                        options => [qw(server network desktop printer)]);

           # Render the form and print it out so our submit button says "Search"
           print $form->render;

       Then, in our "ticket_search.tmpl" HTML file, we would have something
       like this:

           <html>
           <head>
             <title>Search Engine</title>
             <tmpl_var js-head>
           </head>
           <body bgcolor="white">
           <center>
           <p>
           Please enter a term to search the ticket database.
           <p>
           <tmpl_var form-start>
           Search by <tmpl_var field-type> for <tmpl_var field-string>
           <tmpl_var form-submit>
           <p>
           Status: <tmpl_var field-status>
           <p>
           Category: <tmpl_var field-category>
           <p>
           </form>
           </body>
           </html>

       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.

   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:

           #!/usr/bin/perl

           use strict;
           use CGI::FormBuilder;
           use DBI;
           use DBD::Oracle

           my $dbh = DBI->connect('dbi:Oracle:db', 'user', 'pass');

           # We create a new form. Note we've specified very little,
           # since we're 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('user');
           my $sth = $dbh->prepare("select * from user_info where user = '$user'");
           $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 '$user'",
                               header => 1);

   Ex5: add_part.cgi
       This presents a screen for users to add parts to an inventory database.
       Notice how it makes use of the "sticky" 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.

           #!/usr/bin/perl

           use strict;
           use CGI::FormBuilder;

           my $form = CGI::FormBuilder->new(
                           method => 'post',
                           fields => [qw(sn pn model qty comments)],
                           labels => {
                               sn => 'Serial Number',
                               pn => 'Part Number'
                           },
                           sticky => 0,
                           header => 1,
                           required => [qw(sn pn model qty)],
                           validate => {
                                sn  => '/^[PL]\d{2}-\d{4}-\d{4}$/',
                                pn  => '/^[AQM]\d{2}-\d{4}$/',
                                qty => 'INT'
                           },
                           font => 'arial,helvetica'
                      );

           # shrink the qty field for prettiness, lengthen model
           $form->field(name => 'qty',   size => 4);
           $form->field(name => 'model', 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;

       With the exception of the database code, that's the whole application.

   Ex6: Session Management
       This creates a session via "CGI::Session", and ties it in with
       FormBuilder:

           #!/usr/bin/perl

           use CGI::Session;
           use CGI::FormBuilder;

           my $form = CGI::FormBuilder->new(fields => \@fields);

           # Initialize session
           my $session = CGI::Session->new('driver:File',
                                           $form->sessionid,
                                           { Directory=>'/tmp' });

           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;

       Yes, it's pretty much that easy. See CGI::FormBuilder::Multi for how to
       tie this into a multi-page form.

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.

   I'm confused. Why doesn't this work like CGI.pm?
       If you're used to "CGI.pm", you have to do a little bit of a brain
       shift when working with this module.

       FormBuilder is designed to address fields as abstract entities.  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.

       So, if you want a single-option checkbox, simply say something like
       this:

           $form->field(name    => 'join_mailing_list',
                        options => ['Yes']);

       If you want it to be checked by default, you add the "value" arg:

           $form->field(name    => 'join_mailing_list',
                        options => ['Yes'],
                        value   => 'Yes');

       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 FormBuilder creating a single-option field (which is a
       checkbox by default) and selecting the requested value (meaning that
       the box will be checked).

       If you want multiple values, then all you have to do is specify
       multiple options:

           $form->field(name    => 'join_mailing_list',
                        options => ['Yes', 'No'],
                        value   => 'Yes');

       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 "multiple" arg:

           $form->field(name     => 'favorite_colors',
                        options  => [qw(red green blue)],
                        multiple => 1);

       In all of these examples, to get the data back you just use the field()
       method:

           my @colors = $form->field('favorite_colors');

       And the rest is taken care of for you.

   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 FormBuilder only knows about those fields you've told
       it about. So, let's assume that you're going to use a special parameter
       called "mode" to control the mode of your application so that you can
       call it like this:

           myapp.cgi?mode=list&...
           myapp.cgi?mode=edit&...
           myapp.cgi?mode=remove&...

       And so on. You need to do two things. First, you need the "keepextras"
       option:

           my $form = CGI::FormBuilder->new(..., keepextras => 1);

       This will maintain the "mode" field as a hidden field across requests
       automatically. Second, you need to realize that since the "mode" is not
       a defined field, you have to get it via the cgi_param() method:

           my $mode = $form->cgi_param('mode');

       This will allow you to build a large multiscreen application easily,
       even integrating it with modules like "CGI::Application" if you want.

       You can also do this by simply defining "mode" as a field in your
       "fields" declaration. The reason this is discouraged is because when
       iterating over your fields you'll get "mode", which you likely don't
       want (since it's not "real" data).

   Why won't CGI::FormBuilder work with post requests?
       It will, but chances are you're probably doing something like this:

           use CGI qw(:standard);
           use CGI::FormBuilder;

           # Our "mode" parameter determines what we do
           my $mode = param('mode');

           # Change our form based on our mode
           if ($mode eq 'view') {
               my $form = CGI::FormBuilder->new(
                               method => 'post',
                               fields => [qw(...)],
                          );
           } elsif ($mode eq 'edit') {
               my $form = CGI::FormBuilder->new(
                               method => 'post',
                               fields => [qw(...)],
                          );
           }

       The problem is this: Once you read a "post" request, it's gone forever.
       In the above code, what you're doing is having "CGI.pm" read the "post"
       request (on the first call of param()).

       Luckily, there is an easy solution. First, you need to modify your code
       to use the OO form of "CGI.pm". Then, simply specify the "CGI" object
       you create to the "params" option of FormBuilder:

           use CGI;
           use CGI::FormBuilder;

           my $cgi = CGI->new;

           # Our "mode" parameter determines what we do
           my $mode = $cgi->param('mode');

           # Change our form based on our mode
           # Note: since it is post, must specify the 'params' option
           if ($mode eq 'view') {
               my $form = CGI::FormBuilder->new(
                               method => 'post',
                               fields => [qw(...)],
                               params => $cgi      # get CGI params
                          );
           } elsif ($mode eq 'edit') {
               my $form = CGI::FormBuilder->new(
                               method => 'post',
                               fields => [qw(...)],
                               params => $cgi      # get CGI params
                          );
           }

       Or, since FormBuilder gives you a cgi_param() function, you could also
       modify your code so you use FormBuilder exclusively, as in the previous
       question.

   How can I change option XXX based on a conditional?
       To change an option, simply use its accessor at any time:

           my $form = CGI::FormBuilder->new(
                           method => 'post',
                           fields => [qw(name email phone)]
                      );

           my $mode = $form->cgi_param('mode');

           if ($mode eq 'add') {
               $form->title('Add a new entry');
           } elsif ($mode eq 'edit') {
               $form->title('Edit existing entry');

               # do something to select existing values
               my %values = select_values();

               $form->values(\%values);
           }
           print $form->render;

       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:

           my $style = $form->stylesheet;
           $form->stylesheet(0);       # turn off
           $form->stylesheet($style);  # original setting

       You can also specify options to render(), although using the accessors
       is the preferred way.

   How do I manually override the value of a field?
       You must specify the "force" option:

           $form->field(name  => 'name_of_field',
                        value => $value,
                        force => 1);

       If you don't specify "force", then the CGI value will always win.  This
       is because of the stateless nature of the CGI protocol.

   How do I make it so that the values aren't shown in the form?
       Turn off sticky:

           my $form = CGI::FormBuilder->new(... sticky => 0);

       By turning off the "sticky" option, you will still be able to access
       the values, but they won't show up in the form.

   I can't get "validate" to accept my regular expressions!
       You're probably not specifying them within single quotes. See the
       section on "validate" above.

   Can FormBuilder handle file uploads?
       It sure can, and it's really easy too. Just change the "enctype" as an
       option to new():

           use CGI::FormBuilder;
           my $form = CGI::FormBuilder->new(
                           enctype => 'multipart/form-data',
                           method  => 'post',
                           fields  => [qw(filename)]
                      );

           $form->field(name => 'filename', type => 'file');

       And then get to your file the same way as "CGI.pm":

           if ($form->submitted) {
               my $file = $form->field('filename');

               # 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);
           }

       In fact, that's a whole file upload program right there.

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.

       A reference is taken by preceding the variable with a backslash (\).
       In our examples above, you saw something similar to this:

           my @fields = ('name', 'email');   # same as = qw(name email)

           my $form = CGI::FormBuilder->new(fields => \@fields);

       Here, "\@fields" is a reference. Specifically, it's an array reference,
       or "arrayref" for short.

       Similarly, we can do the same thing with hashes:

           my %validate = (
               name  => 'NAME';
               email => 'EMAIL',
           );

           my $form = CGI::FormBuilder->new( ... validate => \%validate);

       Here, "\%validate" is a hash reference, or "hashref".

       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.

       Finally, there are two more types of references: anonymous arrayrefs
       and anonymous hashrefs. These are created with "[]" and "{}",
       respectively. So, for our purposes there is no real difference between
       this code:

           my @fields = qw(name email);
           my %validate = (name => 'NAME', email => 'EMAIL');

           my $form = CGI::FormBuilder->new(
                           fields   => \@fields,
                           validate => \%validate
                      );

       And this code:

           my $form = CGI::FormBuilder->new(
                           fields   => [ qw(name email) ],
                           validate => { name => 'NAME', email => 'EMAIL' }
                      );

       Except that the latter doesn't require that we first create @fields and
       %validate variables.

ENVIRONMENT VARIABLES
   FORMBUILDER_DEBUG
       This toggles the debug flag, so that you can control FormBuilder
       debugging globally. Helpful in mod_perl.

NOTES
       Parameters beginning with a leading underscore are reserved for future
       use by this module. Use at your own peril.

       The field() method has the alias param() for compatibility with other
       modules, allowing you to pass a $form around just like a $cgi object.

       The output of the HTML generated natively may change slightly from
       release to release. If you need precise control, use a template.

       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 $ENV{PATH}". If so, make sure you
       are setting $ENV{PATH} at the top of your script.

ACKNOWLEDGEMENTS
       This module has really taken off, thanks to very useful input, bug
       reports, and encouraging feedback from a number of people, including:

           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

       Thanks!

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

REVISION
       $Id: FormBuilder.pm 65 2006-09-07 18:11:43Z nwiger $

AUTHOR
       Copyright (c) Nate Wiger <http://nateware.com>. All Rights Reserved.

       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.

perl v5.40.0                      2024-09-01               CGI::FormBuilder(3)