CGI::FormBuilder - Easily generate and process stateful forms

    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(
                    fields   => [qw(name email phone gender)],
                    header   => 1,
                    method   => 'POST',
                    values   => $dbval,
                    validate => {
                       email => 'EMAIL',
                       phone => '/^1?-?\d{3}-?\d{3}-?\d{4}$/',
                    },
                    required => 'ALL',
                    stylesheet => '/path/to/style.css',
               );

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

    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->{name},  $field->{email},
                       $field->{phone}, $field->{gender});

        # Show confirmation screen
        print $form->confirm;
    } else {
        # Print out the form
        print $form->render;
    }

If this is your first time using FormBuilder, you should check out the website for tutorials and examples:

    www.formbuilder.org

You should also consider joining the mailing list by sending an email to:

    fbusers-subscribe@formbuilder.org

There are some pretty smart people on the list that can help you out.

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 CWCGI.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:

- Viewing fields as entities (instead of just params), where the HTML representation, CGI values, validation, and so on are properties of each field.

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

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

- Pluggable support for external template engines, such as CWHTML::Template, CWText::Template, CWTemplate Toolkit, and CWCGI::FastTemplate.

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 | $str,           # "Reset" button
       submit     => 0 | $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,              # 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   => $filename | \%hash | $object,  # locale 
       template   => $filename | \%hash | $object,  # custom HTML

       # Formatting options
       body       => \%attr,             # {background => 'black'}
       disabled   => 0 | 1,              # display as grayed-out?
       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,            # prefix for class= ("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
    $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
       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

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

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 CWvalidate 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 CWonsubmit 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 CWvalidate 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 CWsubmitted() 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 CWfield() 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 CWfield() 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 CWHTML::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 CWtemplate 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 CW\@fields, skip down to the brief section entitled REFERENCES at the bottom of this document (it's short).

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.

This method creates a new CW$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, you can also now initialize FormBuilder from an external file:

    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 CWnew(), can also be manipulated directly with a method of the same name. For example, to change the CWheader and CWstylesheet 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: 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 CW<body> tag verbatim (for example, bgcolor, alink, etc). See the CWfieldattr tag for more details, and also the CWtemplate option.

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 CWfields 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 CWvalues 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 CWfields 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 CWfield() 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 CWstylesheet option, this is fairly useless.

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. The font face to use for the form. This is output as a series of CW<font> tags for best browser compatibility, and will even 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 CW<font> tag:

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

That becomes:

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

I use this option all the time.

header => 0 | 1

If set to 1, a valid CWContent-type header will be printed out, along with a whole bunch of HTML CW<body> code, a CW<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. This is verbatime JavaScript that will go into the CWvalidate JavaScript function. It is useful for adding your own verbatim 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 CWform._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 CWHERE string in single quotes, as shown above. 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 CWcgi_param(), NOT CWfield(), to get to 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 CWmode and CWcompany.

labels => \%hash

Like CWvalues, this is a list of key/value pairs where the keys are the names of CWfields 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.

linebreaks => 0 | 1

If set to 1, line breaks will be inserted after each input field. By default this is figured out for you, so usually not needed.

method => 'POST' | 'GET'

The type of CGI method to use, either CWPOST or CWGET. Defaults to CWGET if nothing is specified. Note that for forms that cause changes on the server, such as database inserts, you should use the CWPOST method. This option overrides the default FormBuilder messages in order to provide multilingual support (or just different text for the picky ones). For details on this option, please refer to CGI::FormBuilder::Messages. 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 DOM CWid 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 CWfield() for the CWdepartment and CWin_stock fields to set options individually. This specifies an object from which the parameters should be derived. The object must have a CWparam() 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 CWmod_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 CWCGI.pm object separately and are using a CWPOST 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 CWrequired option is not specified, by default any fields named in CWvalidate will be required. In addition, the CWrequired option also takes two other settings, the strings CWALL and CWNONE. If you specify CWALL, then all fields are required. If you specify CWNONE, 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 CWemail field optional, but if filled in then it would have to match the CWEMAIL pattern. In addition, it is very important to note that if the CWrequired and CWvalidate options are specified, then they are taken as an intersection. That is, only those fields specified as CWrequired 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(n)]
               );

This would make the CWname field mandatory, but the CWemail field optional. However, if CWemail is filled in, then it must match the builtin CWEMAIL pattern. 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. 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 CWselectnum 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 CWmultiple option is specified and the field has less than CWselectnum 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 CWsmartness to CW0. If you want it to be really smart, like figuring out what type of validation routines to use for you, set it to CW2. It defaults to CW1.

sortopts => 'NAME' | 'NUM' | 1 | \&sub

If specified to CWnew(), this has the same effect as the same-named option to CWfield(), only it applies to all fields. 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. 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 CWsubmitted() function:

    my $clicked = $form->submitted;

So if the user clicked Add A Gift then that is what would end up in the variable CW$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. This string is prefixed to stylesheet class names. See below. This option turns on stylesheets in the HTML output by FormBuilder. Each element is prefixed by whatever CWstyleclass is set to (fb_ by default). It is up to you to provide the actual style definitions. If you provide a CW$path rather than just a 1/0 toggle, then that CW$path will be included in a CW<link> tag as well.

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 CW1, or force it out of one with CW0. If you specify a hashref instead, then these will be used to create the CW<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 CW<td> and CW<tr> elements as well in the same fashion. This points to a filename that contains an CWHTML::Template compatible template to use to layout the HTML. You can also specify the CWtemplate option as a reference to a hash, allowing you to further customize the template processing options, or use other template engines. If CWtemplate points to a sub reference, that routine is called and its return value directly returned. If it is an object, then that object's CWrender() routine is called and its value returned. For lots more information, please see CGI::FormBuilder::Template. This is text that is included below the title but above the actual form. Useful if you want to say something simple like Contact CW$adm for more help, but if you want lots of text check out the CWtemplate option above. This takes a string to use as the title of the form.

values => \%hash | \@array

The CWvalues 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 CWfields option.

validate => \%hash

This option takes a hashref of key/value pairs. Each key is the name of a field from the CWfields option, or the string CWALL 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 CWvalidate option also toggles each field to make it required. However, you can use the CWrequired option to change this, see it for more details. Let's look at a concrete example:

    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',
                            perl       => 'eq $form->field("password")'
                        },
                    },
               );

    # 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 CWqr// will NOT work. Note that for both the CWjavascript and CWperl hashref code options, the form will be present as the variable named CWform. For the Perl code, you actually get a complete CW$form object meaning that you have full access to all its methods (although the CWfield() method is probably the only one you'll need for validation). In addition to taking any regular expression you'd like, the CWvalidate 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.

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

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 CWrender(), 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 CWrender() will still have the header and stylesheet options in either case.

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 CWfield() 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 CWcolor in the hashref. In this case you'll need to access it via CWfield() to get them all:

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

The CWname option is described first, and the remaining options are in order: 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

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

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

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

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 CWsessionid has been set. This also requires that CWheader be set as well, since the cookie is wrapped in the header. Defaults to 1, meaning it will automatically work if you turn on CWheader.

force => 0 | 1

This is used in conjunction with the CWvalue option to forcibly override a field's value. See below under the CWvalue option for more details. For compatibility with CWCGI.pm, you can also call this option CWoverride instead, but don't tell anyone. 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 CWtext and CWfile field types. If you set CWgrowable 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 CW$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. 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 CWselect to CWradio or CWcheckbox, then the action changes from CWonchange to CWonclick. 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 CW@cards:

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

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

You get the idea. You can use this to specify your own custom message for the field, which will be printed if it fails validation. The CWjsmessage option affects the JavaScript popup box, and the CWmessage option affects what is printed out if the server-side validation fails. If CWmessage is specified but not CWjsmessage, then CWmessage 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 CW%s will be filled in with the field's CWlabel. 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 BIfield() is outdated. You can get the same effect by passing data structures directly to the CWoptions argument (see below). If you have well-named data, check out the CWnameopts 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 CWoptions 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. Like CWjsmessage, this customizes the output error string if server-side validation fails for the field. The CWmessage option will also be used for JavaScript messages if it is specified but CWjsmessage is not. See above under CWjsmessage 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 CWoptions 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 CWtype 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);

As would, in fact, this code:

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

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

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 CWvalidate and CWrequired options to CWnew().

sortopts => 'NAME' | 'NUM' | 1 | \&sub

If set, and there are options, then the options will be sorted in the specified order. For example:

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

Would sort the CW@cats options in alphabetic (CWNAME) order. The option CWNUM 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 CWsort() expects. 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. The CWvalue 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 CWforce 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 CWconfirm() screen instead of the actual number.

validate => '/regex/'

Similar to the CWvalidate option used in CWnew(), 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. In addition to the above tags, the CWfield() 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 CW$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 CWFormField in your stylesheet.) See also the CWfieldattr option which provides global attributes to all fields.

The above CWfield() 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 CWCGI.pm's CWparam() method, so consult those docs for more information.

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.

This gets and sets the sessionid, which is stored in the special form field CW_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 CWCGI::Session.

Since you can set the session id via the CW_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 CW0123-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 CWheader is set, then FormBuilder will also automatically generate a cookie for you.

See EXAMPLES for CWCGI::Session example.

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 CWvalidate() 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 CWname option described above.

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

You can also specify the name of an optional field which you want to watch instead of the default CW_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, CWsubmitted() would return false since the CW_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.)

This validates the form based on the validation criteria passed into CWnew() via the CWvalidate option. In addition, you can specify additional criteria to check that will be valid for just that call of CWvalidate(). 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}$/');
    }

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

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 CWrender(), 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.

This sends a confirmation email to the named addresses. The CWto argument is required; everything else is optional. If no CWfrom is specified then it will be set to the address CWauto-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.

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: Nathan Wiger
    email: nate@wiger.org
    colors: red green blue

And so on. You can change this by specifying the CWdelimiter and CWjoiner options. For example this:

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

Would produce an email like this:

    name=Nathan 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 CWjoiner.

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

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

Returns a CWCGI.pm header, but only if CWheader => 1 is set.

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

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

This returns a query string similar to CWCGI.pm, but ONLY containing form fields and any CWkeepextras, if specified. Other params are ignored.

This returns a self url, similar to CWCGI.pm, but again ONLY with form fields.

An alias for CW$form->action.

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

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

    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 CWstate, a radio group for CWsend_me_emails, and normal text boxes for the rest. It will then validate all the fields, using specific patterns for those fields specified to CWvalidate.

Here's an example that adds some fields dynamically, and uses the CWdebug option spit out gook:

    #!/usr/bin/perl -w

    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 CWuser_name field will still be validated if filled in.

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

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

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

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

This presents a screen for users to add parts to an inventory database. Notice how it makes use of the CWsticky 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 -w

    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.

This creates a session via CWCGI::Session, and ties it in with FormBuilder:

    #!/usr/bin/perl -w

    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.

There are a couple questions and subtle traps that seem to poke people on a regular basis. Here are some hints.

If you're used to CWCGI.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 CWvalue 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 CWmultiple 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 CWfield() method:

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

And the rest is taken care of for you.

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 CWmode 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 CWkeepextras option:

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

This will maintain the CWmode field as a hidden field across requests automatically. Second, you need to realize that since the CWmode is not a defined field, you have to get it via the CWcgi_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 CWCGI::Application if you want.

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

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 CWPOST request, it's gone forever. In the above code, what you're doing is having CWCGI.pm read the CWPOST request (on the first call of CWparam()).

Luckily, there is an easy solution. First, you need to modify your code to use the OO form of CWCGI.pm. Then, simply specify the CWCGI object you create to the CWparams 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 CWcgi_param() function, you could also modify your code so you use FormBuilder exclusively, as in the previous question.

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 CWrender(), although using the accessors is the preferred way.

You must specify the CWforce option:

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

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

Turn off sticky:

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

By turning off the CWsticky option, you will still be able to access the values, but they won't show up in the form. You're probably not specifying them within single quotes. See the section on CWvalidate above.

It sure can, and it's really easy too. Just change the CWenctype as an option to CWnew():

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

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, CW\@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, CW\%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 CW[] and CW{}, 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 CW@fields and CW%validate variables.

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

The CWfield() method has the alias CWparam() for compatibility with other modules, allowing you to pass a CW$form around just like a CW$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 CW$ENV{PATH}. If so, make sure you are setting CW$ENV{PATH} at the top of your script.

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
    Bob Egert
    Peter Eichman
    Adam Foxson
    Jorge Gonzalez
    Florian Helmberger
    Mark Houliston
    Robert James Kaes
    Dimitry Kharitonov
    Randy Kobes
    William Large
    Kevin Lubic
    Robert Mathews
    Mehryar
    Koos Pol
    Shawn Poulson
    Dan Collis Puro
    David Siegal
    Stephan Springl
    Ryan Tate
    John Theus
    Remi Turboult
    Andy Wardley
    Raphael Wegmann
    Emanuele Zeppieri

Thanks!

CGI::FormBuilder::Template, CGI::FormBuilder::Messages, CGI::FormBuilder::Source::File, CGI::FormBuilder::Field, CGI::FormBuilder::Util, HTML::Template, Text::Template, Template Toolkit, CGI, CGI::Application

$Id: FormBuilder.pm,v 1.58 2005/04/06 18:46:32 nwiger Exp $

Copyright (c) 2000-2005 Nathan Wiger, Sun Microsystems <nate@sun.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.