=head1 NAME

README - README for FormBuilder 3.0, please also see Changes

=head1 DESCRIPTION

I hate form generation and validation because the majority of the
process is tedious and mindless. In addition to being boring, there
is too much room for simple error, which could render your 
application insecure or just plain useless.

So I wrote B<FormBuilder> to try and get rid rid of the stoopid
parts, as well as take care of some tricky parts. As a result,
you can build a complete application with something like this:

    use CGI::FormBuilder;

    # Assume we did a DBI query to get existing values
    my $dbval = $sth->fetchrow_hashref;

    # First create our form
    my $form = CGI::FormBuilder->new(
                    fields   => [qw(name email phone gender)],
                    header   => 1,
                    method   => 'POST',
                    values   => $dbval,
                    validate => {
                       email => 'EMAIL',
                       phone => '/^1?-?\d{3}-?\d{3}-?\d{4}$/',
                    },
                    required => 'ALL',
                    stylesheet => '/path/to/style.css',
               );

    # Change gender field to have options
    $form->field(name => 'gender', options => [qw(Male Female)] );

    if ($form->submitted && $form->validate) {
        # Get form fields as hashref
        my $fields = $form->fields;

        # 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;
    } else {
        # Print out the form
        print $form->render;
    }

That simple bit of code would print out an entire form, laid out in a
table. Your default database values would be filled in from the DBI
hashref. It would also handle stickiness across multiple submissions
correctly, and it will also be able to tell if it's been submitted.
Finally, it will do both JavaScript and server-side validation too.

=head1 KEY FEATURES

Here's the main stuff that I think is cool:

=head2 Input field abstraction

You simply define your fields and their values, and this module will
take care of figuring out the rest. B<FormBuilder> will automatically
generate the appropriate input fields (input, select, radio, etc),
even changing any JavaScript actions appropriately.

=head2 Easy handling of defaults

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 C<field()> method to get the data you'll get the correct
value.

=head2 Correct stickiness

Stickiness is a PITA. B<FormBuilder> correctly handles even multiple values
selected in a multiple select list, integrated with proper handling of defaults.

=head2 Multiple submit mode support

Related to the above, B<FormBuilder> allows you to reliably tell whether
the person clicked on the C<Update> or C<Delete> button of your form, 
normally a big pain.

=head2 Robust field validation

Form validation sucks, and this is where B<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 B<FormBuilder> will correctly check even multivalued inputs.

=head2 Template driver support

B<FormBuilder> can natively "drive" several major templating engines,
including C<HTML::Template>, C<Template Toolkit>, and C<Text::Template>.
if you want to build a form application with a template in less that 20
lines of Perl, B<FormBuilder> is for you.

=head1 SUPPORT

There is a whole website devoted to this module:

    www.formbuilder.org

There are online tutorials, code examples, full documentation, and much
more. There is also a mailing list with some pretty smart people on it:

    fbusers-subscribe@formbuilder.org

Have fun!

=head1 INSTALLATION

For details on installation, please read the file C<INSTALL>.

=head1 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.