The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CGI-FormBuilder-3.02
River stage two • 11 direct dependents • 16 total dependents
++

Changes for 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()".

Documentation

Changes
Changes in FormBuilder 3.0, please also see the README
INSTALL
how to install FormBuilder 3.0
README
README for FormBuilder 3.0, please also see Changes

Modules

CGI::FormBuilder
Easily generate and process stateful forms
CGI::FormBuilder::Field
Internally used to create a FormBuilder field
CGI::FormBuilder::Messages
Localized message support for FormBuilder
CGI::FormBuilder::Multi
Create multi-page FormBuilder forms
CGI::FormBuilder::Source
Source adapters for FormBuilder
CGI::FormBuilder::Source::File
Initialize FormBuilder from external file
CGI::FormBuilder::Template
Template adapters for FormBuilder
CGI::FormBuilder::Template::Fast
FormBuilder interface to CGI::FastTemplate
CGI::FormBuilder::Template::HTML
FormBuilder interface to HTML::Template
CGI::FormBuilder::Template::TT2
FormBuilder interface to Template Toolkit
CGI::FormBuilder::Template::Text
FormBuilder interface to Text::Template
CGI::FormBuilder::Util
Utility functions for FormBuilder

Other files