Perl Form Builder ::Features ::Download ::Tutorial ::Examples
::Documentation ::FormBuilder Google Group ::Old List Archives ::Contribute
Note: The mailing list is has been replaced by the Google FormBuilder Group

Release Notes for 3.0202

Here's what's new in FormBuilder 3.0202 (browse), along with any known issues or bugs still in the works.

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
In order to allow the second form, you must specify the fieldsubs option to new().

VERSION 3.0202

This is a bugfix release that patches the following problems:
  • missing $form->name accessor
  • $form->confirm displaying wrong value for radio groups
  • $form->new(messages => $file) not reading file (tries to bless directly)
  • added $form->field(delete => 1) option
  • disabling field comment on static fields
  • fixing $form->field(disabled => 0)
  • redone messages joiner on array passing (internals thing)
The changed files are: CGI/FormBuilder.pm CGI/FormBuilder/Field.pm CGI/FormBuilder/Messages.pm All other sub-modules shipped are identical to the 3.02 versions; those modules retain the same version and signature.

VERSION 3.02

Multi-Page Form Support

A new module, CGI::FormBuilder::Multi, has been added to handle the navigation and state of multi-page forms. A multi-page form is actually composed of several individual forms, tied together with the special CGI param _page:
        my $multi = CGI::FormBuilder::Multi->new(
                         # first args are hashrefs per-form
                         \%form1_opts,
                         \%form2_opts,
                         \%form3_opts,

                         # remaining options apply to all forms
                         header => 1,
                         method => 'POST',
                    );

        my $form = $multi->form;    # current form

        if ($form->submitted && $form->validate) {

            # you write this
            do_data_update($form->fields);

            # last page?
            if ($multi->page == $multi->pages) {
                print $form->confirm;
                exit;
            }

            $multi->page++;          # next page counter
            $form = $multi->form;    # fetch next page's form
        }
        print $form->render;
For more details, see CGI::FormBuilder::Multi.

External Source File

Inspired by Peter Eichman's Text::FormBuilder, the new source option has been added to new() which enables the use of an external config file to initialize FormBuilder. This file takes the format:
        # sample config file
        method: POST
        header: 1
        submit: Update, Delete

        fields:
            fname:
                label: First Name
                size:  50
                validate: NAME
            lname:
                label: Last Name
                size:  40
                validate: NAME
            sex:
                label:    Gender
                options:  M=Male, F=Female
                jsclick:  javascript:alert(Change your mind??);
                validate: M,F

        required: ALL

        messages:
            form_invalid_text:  Please correct the following fields:
            form_required_text: Please fill in all <b>bold</b> fields.
You can even pre-parse this file, and generate a module from it which you can then reuse in multiple scripts using the write_module() function. For more details, see CGI::FormBuilder::Source::File.

Other Fields

The new other option has been added to field(). If specified, a text box will be added to the right of the field, and its value will be used if the main field is not filled in. It will be subject to the same required and validation checks as the main field:
        $form->field(name     => 'favorite_color',
                     options  => [qw(Red Green Blue)],
                     validate => 'NAME',
                     other    => 1);     # allow other
This would create HTML something like this:
        Favorite Color: []Red []Green []Blue []Other: [____________]
The text Other: is controlled by the message form_other_default.

Growable Fields

Thanks to a patch from Peter Eichman, field() now also accepts a growable option. This option enables some JavaScript hooks that add an Additional [label] button on text and file fields:
        Data File: [______________] [Additional Data File]
When you click on the Additional Data File button, another box will be appended, allowing you to add more files. The values are then retrieved in the usual fashion:
        my @files = $form->field('data_file');
Like other fields, all elements are subject to validation checks. The text Additional %s is controlled by the message form_grow_default.

Support for CGI::FastTemplate

Thanks once again to Peter Eichman (busy guy), the module CGI::FormBuilder::Template::Fast has been included. This adds the template type Fast as an interface to CGI::FastTemplate:
        my $form = CGI::FormBuilder->new(
                        template => {
                            type => 'Fast',
                            define => {
                                form  => 'form.tmpl',
                                field => 'field.tmpl',
                            }
                        }
See CGI::FormBuilder::Template::Fast for more details. Thanks again Peter!

Subclassable Templates and tmpl_param()

The 2.x tmpl_param() method has been reimplemented finally. In addition, the included template modules are now completely subclassable, meaning that you can create an entire template engine with something like this:
        package My::HTML::Template;

        use CGI::FormBuilder::Template::HTML;
        use base 'CGI::FormBuilder::Template::HTML';

        # new() is inherited

        sub render {
            my $self = shift;
            my $form = shift;   # complete form object

            # do any special actions here

            $self->SUPER::render;
        }
For more details, see CGI::FormBuilder::Template.

Message Changes

All messages were reworded to make them shorter and easier to read. The phrase You must was removed from all of them. To see the new messages, cut-and-paste this code:
        perl -MCGI::FormBuilder::Messages \
             -e 'CGI::FormBuilder::Messages->messages'
In addition, the form_submit_default and form_reset_default messages were not even being used, and field labels were not being properly highlighted on error. These problems have been fixed.

Autoloaded Fields

The 2.x feature of $form->$fieldname() has been reimplemented, but using it requires the fieldsubs option:
        my $form = CGI::FormBuilder->new(fields => \@f, fieldsubs => 1);
Read the docs for some caveats.

Disabled Form

Similar to a static form, you can set disabled => 1 in new() or render() to display a form with grayed-out input boxes. You can also set this on a per-field basis using field().

Verbatim HTML Options

If you want to include HTML in your field options, set cleanopts to 0 in field() (for one field) or new() (for all fields).

Compatibility Methods

For compatibility with other modules, FormBuilder now includes param(), query_string(), self_url(), and script_name().

VERSION 3.01

This was a bugfix release, including the following changes:
  • fixed major problems with keepextras, including a reversed ismember test
  • added debug messages to keepextras and changed a few other debugs
  • added patch from Peter Eichman to fix scalar $field->tag and $field->tag_value
  • converted most all XHTML generation methods to only returning scalars
  • fixed the columns option which was totally broken for radio buttons
  • added a feature to plop in {border => 0} in columns as well
  • added the 2.x 'override' alias for field() 'force' which was missing
  • also added a 'defaults' alias for field() 'value' for CGI.pm happiness
  • more tests since there were way too many bugs
In addition there were many documentation updates and changes.

VERSION 3.00

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.

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

Many messages have been reworded, and several new messages were added to make it easier to customize individual text. In addition, you can now specify messages to individual fields:
        $form->field(name => 'email',
                     message => 'Please enter a valid email address');
For more details, see CGI::FormBuilder::Messages.

HTML::Entities encoding

HTML character encoding is now dispatched to HTML::Entities, if available. This can be downloaded as part of the HTML::Parser module set on CPAN.

Documentation

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

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.
FormBuilder is © Nate Wiger, with contributions from many people.
Nateware