/ 
CGI-FormBuilder-3.000
River stage two • 11 direct dependents • 16 total dependents
/ Changes

NAME

Changes - Changes in FormBuilder 3.0, please also see the README

COMPATIBILITY

FormBuilder 3.0 should be completely compatible with FormBuilder 2.x, with the singular exception that you can no longer use the shortcut autoload style of getting to fields:

$form->field(name => 'category', options => \@opt);
$form->category(options => \@opt);      # WRONG

The second form is now used to manipulate $form attributes.

INTERNALS

The internals have been completely rewritten, nearly from the ground up. All of the major functions have been split into methods, and objects have been created for the form, fields, messages, CGI params, and so on. Several new sub-modules have been created, including:

CGI::FormBuilder::Field
CGI::FormBuilder::Messages
CGI::FormBuilder::Template
CGI::FormBuilder::Template::HTML
CGI::FormBuilder::Template::Text
CGI::FormBuilder::Template::TT2

Many of these modules can be subclassed and overridden if desired. In addition, the template engine has been rewritten to allow "plugging in" of additional template modules, simply by specifying the name of the module to the 'template' option in new().

For more details, see the man pages for the individual modules above.

NEW FEATURES

Several new features have been added which FormBuilder 2.x could not support:

Style Sheets

Stylesheets are now generated if the stylesheet option is specified to FormBuilder. This can either be 1 to turn it on, or a full path to a style sheet to include. When used, all tags are then output with a class attribute, named styleclass plus the name of the tag:

my $form = CGI::FormBuilder->new(
                fields => [qw/name email/],
                styleclass => 'myFB',   # default is "fb_"
                stylesheet => 1,        # turn on style
           );
            
print $form->render;

# HTML will include
#   <input class="myFBname" id="name" name="name" type="text" />
#   <input class="myFBemail" id="email" name="email" type="text" />

Compliant XHTML

The output should be fully-compliant XHTML finally. Really. Maybe.

Attributes and Field Objects

Individual accessors have been added for every attribute that FormBuilder maintains. For example, here's a snippet of code to demonstrate:

if ($form->stylesheet) {
    # loop thru fields, changing class
    for ($form->fields) {
        next if /_date$/;   # skip fields named "XXX_date"

        # each field is a stringifiable object with accessors
        if ($_->options) {
            # has options
            $_->class('my_opt_style');
        } else {
            # plain text box
            $_->class('my_text_style');
        }
    }
}

This code checks to see if the stylesheet property has been set on the main $form. If so, then it loops thru all the fields, skipping those named XXX_date. Of the remaining fields, those that have options have their class attribute changed to my_opt_style, and those without options have it set to my_text_style.

In addition, you can individually render every part of the form yourself. by calling the appropriate method. For example:

print $form->header;      # just the header
print $form->script;      # opening JavaScript
print $form->title;       # form title
print $form->start;       # opening <form> tag
for ($form->fields) {
    print $_->label;      # each field's human label
    print $_->tag;        # each field's <input> tag
}
print $form->end;         # closing </form> tag

For a complete list of accessors, see the documentation for both CGI::FormBuilder and CGI::FormBuilder::Field.

Messages

Some messages have been reworded to make it easier to change just a single message, and a couple new messages were added as well:

js_noscript             <p><font color="red"><b>Please enable JavaScript or
                        use a newer browser.</b></font></p>

form_required_text      <p>Fields that are %s highlighted %s are required.</p>
form_required_opentag   <b>
form_required_closetag  </b>

form_invalid_text       <p>%s error(s) were encountered with your submission.
                        Please correct the fields %s highlighted %s below.</p>
form_invalid_opentag    <font color="red"><b>
form_invalid_closetag   </font></b>

js_invalid_default      - You must enter a valid value for the "%s" field
form_invalid_default    You must enter a valid value

For more details, see CGI::FormBuilder::Messages.

Bug fixes

There were several longstanding edge-case bugs that just could not be fixed, because the 2.x internals were too nasty.

Documentation

Documentation has been updated and somewhat reorganized, which was long overdue.

Versioning

Versions are now maintained in full Perl internal format. This allows you to say:

use CGI::FormBuilder v3.1

To ensure you get FormBuilder at least 3.001

AUTHOR

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.