Changes - Changes in FormBuilder 3.0, please also see the README
FormBuilder 3.x 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().
fieldsubs
new()
Maintenance release with a couple new features: support for "charset: utf8" in Source::File, add_before_option/add_after_option c/o Victor Porton, and support for HTML5 type names c/o Wolfgang Radke.
Source::File
Bugfix release to repair a memory leak and a few "other" field edge cases.
Just a short time after 3.04, several new features evolved very quickly:
A new fieldsets option to new() and a fieldset option to the field() method can be used to organize your form into sections. Currently works with the built-in <table> and new <div> renderer only, but template support is in the works.
fieldsets
fieldset
field()
<table>
<div>
In addition to the builtin <table> rendering module, a new Div rendering template has been included as well. If you select this, you get a table-free form which you can manipulate using stylesheets:
Div
$form->new(template => {type => 'div'});
This provides a couple additional benefits, like separate divs for every submit button.
A couple additional CSS classes were added, wrapping around the fields as a unit for better styling. The <form> tag now gets a .fb_form style as well.
<form>
.fb_form
A couple bugs were introduced in 3.04 that have been fixed, and more tests added.
In addition to the below features, a new Catalyst FormBuilder plugin is available on CPAN, Catalyst::Plugin::FormBuilder.
Catalyst::Plugin::FormBuilder
You can now use $form->prepare() to get back an expanded hashref just before $form->render() is called. This allows you to use FormBuilder with Catalyst or other frameworks more easily, where the rendering is done elsewhere:
$form->prepare()
$form->render()
my %expansion = $form->prepare;
This could be passed directly to, say, Template Toolkit without having to use FormBuilder's Template Toolkit support.
This is used the convert fields on the fly into objects or other values. For example, you could convert a "date" field into a DateTime object. Nice patch from Mark Hedges, check it out.
Thanks to Recai Oktas.
This can be queried in templates. To see if a field is missing altogether, you can check "field.missing" or "missing-field" depending on your template engine of choice.
puke
belch
FormBuilder now uses Carp and @CARP_NOT to handle its errors. As such, you will probably notice some differences in error output. The benefit is that setting debug will give you a stack trace on fatal errors.
Carp
@CARP_NOT
debug
Moved the render_builtin() method to the above module, to unify the rendering schemes.
render_builtin()
Setting this has the same effect as using the debug option.
Removed all the stub docs from Field::* and Messages::* to make CPAN happy.
Field::*
Messages::*
This is a bugfix release to repair these main items:
- optgroups bugfix for complex arrays - removal of HTML::Entities support due to utf8 issues - new es_ES Messages module with better translations - a patch from Mark Hedges to enable plugin modules for mailresults()
The rest of the features remain the same as below.
Each field is now rendered by its own class, named for the field type. For example, text fields are rendered by CGI::FormBuilder::Field::text. This allows you to create custom field types and plugging them in by creating your own CGI::FormBuilder::Field::whatever_you_want module. Thanks to Peter Eichman for his contributions to this scheme.
CGI::FormBuilder::Field::text
CGI::FormBuilder::Field::whatever_you_want
All messages are now handled in a similar way to field types: They are delegated to CGI::FormBuilder::Messages::locale where "locale" is the appropriate string such as "en_US" or "da_DK". A number of localizations are included as part of the standard distribution.
CGI::FormBuilder::Messages::locale
There are two ways to use these messages: Either the 'auto' messages mode or by specifying a specific locale:
my $form = CGI::FormBuilder->new(messages => 'auto'); # check client my $form = CGI::FormBuilder->new(messages => ':da_DK'); # specified
You can create your own messages by copying _example.pm and modifying it for your language. When using messages in this way, the HTTP Charset is changed to utf-8.
_example.pm
utf-8
By using the field() option optgroups, you can now cause select fields to automatically generate optgroup tags:
optgroups
$form->field(name => 'browser', options => \@opt, optgroups => 1);
See the documentation on optgroups for more details.
Thanks to another great patch from Peter Eichman, Data::FormValidator is supported as a validation option to new(), just by passing it in as an object. See the documentation on validate for more information.
Data::FormValidator
validate
You can now sort options by LABELNAME or LABELNUM, similar to the value-based sorting of NAME and NUM. See the documentation for more details.
LABELNAME
LABELNUM
NAME
NUM
Generated code now validates against http://validator.w3.org. This includes stuff like lowercase get and post methods, lowercase onchange and onsubmit actions, and so on.
get
post
onchange
onsubmit
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:
CGI::FormBuilder::Multi
_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.
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:
Text::FormBuilder
source
# 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.
write_module()
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:
other
$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.
form_other_default
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:
growable
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.
form_grow_default
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:
CGI::FormBuilder::Template::Fast
Fast
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!
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:
tmpl_param()
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.
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.
form_submit_default
form_reset_default
The 2.x feature of $form->$fieldname() has been reimplemented, but using it requires the fieldsubs option:
$form->$fieldname()
my $form = CGI::FormBuilder->new(fields => \@f, fieldsubs => 1);
Read the docs for some caveats.
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().
disabled => 1
render()
If you want to include HTML in your field options, set cleanopts to 0 in field() (for one field) or new() (for all fields).
cleanopts
For compatibility with other modules, FormBuilder now includes param(), query_string(), self_url(), and script_name().
param()
query_string()
self_url()
script_name()
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.
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.
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:
stylesheet
1
class
styleclass
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" />
The output should be fully-compliant XHTML finally. Really. Maybe.
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.
$form
XXX_date
my_opt_style
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.
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.
CGI::FormBuilder::Messages
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.
HTML::Entities
HTML::Parser
Documentation has been updated and somewhat reorganized, which was long overdue.
Copyright (c) Nate Wiger. 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.
To install CGI::FormBuilder, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::FormBuilder
CPAN shell
perl -MCPAN -e shell install CGI::FormBuilder
For more information on module installation, please visit the detailed CPAN module installation guide.