README - README for FormBuilder 3.0, please also see Changes
For details on installation, please read the file INSTALL.
INSTALL
FormBuilder is a fully-functional form engine with numerous features. It is far more than a form-generating module. For example, you can build a complete application with something as simple as this:
use CGI::FormBuilder; # Let's assume we did a DBI query to get existing values my $dbval = $sth->fetchrow_hashref; my $form = CGI::FormBuilder->new( method => 'POST', fields => [qw/name email phone gender/], values => $dbval, validate => { email => 'EMAIL', phone => 'PHONE' }, required => 'ALL', header => 1, stylesheet => '/path/to/style.css', ); # Change gender field to have options $form->field(name => 'gender', options => [qw/Male Female/]); if ($form->submitted && $form->validate) { my $fields = $form->fields; # get form fields as hashref # Do something to update your data (you would write this) do_data_update($fields->{name}, $fields->{email}, $fields->{phone}, $fields->{gender}); # Show confirmation screen print $form->confirm; # Email the person a brief confirmation $form->mailconfirm(to => $fields->{email}); } else { # Print out the form print $form->render; }
That simple bit of code would print out an entire form, laid out in a table, complete with JavaScript validation code. Default values would be filled in from the DBI hashref. It would also handle stickiness across multiple submissions correctly. It will also be able to tell if it's been submitted, and do server-side validation too.
Overall, I just plain hate form generation and validation because the majority of the process is tedious and mindless. FormBuilder tries to get rid of the stoopid parts.
There are a lot of form modules, scripts, etc out there. So why use this one? Well, that's up to you, but here are the features that I feel are the real benefits of FormBuilder:
This module tries to Do What I Mean. Tell it the fields you care about, and it takes care of all the stupid HTML and JavaScript generation and processing for you. It also gives you back the correct values that you want. It will even label your fields automatically.
Do What I Mean
You simply define your fields and their values, and this module will take care of figuring out what representation is best. It will then generate the appropriate input fields (input, select, radio, etc), even changing any JavaScript actions appropriately.
Just specify a hash of values to use as the defaults for your fields. This will be searched case-insensitively and displayed in the form. What's more, if the user enters something via the CGI that overrides a default, when you use the field() method to get the data you'll get the correct value.
field()
Stickiness is a PITA. FormBuilder correctly handles even multiple values selected in a multiple select list, integrated with proper handling of defaults.
Form validation sucks, and this is where FormBuilder is a big help. It has tons of builtin patterns, and will even generate gobs of JavaScript validation code for you. You can specify your own regexps as well, and FormBuilder will correctly check even multivalued inputs.
FormBuilder allows you to reliably tell whether the person clicked on the Update or Delete button of your form, normally a big pain.
Update
Delete
FormBuilder can natively "drive" several major templating engines, including HTML::Template, Template Toolkit, and Text::Template. if you want to build a form application with a template in less that 20 lines of Perl, FormBuilder is for you.
HTML::Template
Template Toolkit
Text::Template
Installation is standard, the same way as for other Perl modules.
perl Makefile.PL make make test make install
There is a website devoted to this module at www.formbuilder.org which has tutorials, code examples, full documentation, and much more.
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.
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.