view release on metacpan or  search on metacpan

lib/CGI/FormBuilder.pod  view on Meta::CPAN

    if ($form->submitted) { ... }

Or to retrieve the button that was actually clicked on in the
case of multiple submit buttons:

    if ($form->submitted eq 'Update') {
        ...
    } elsif ($form->submitted eq 'Delete') {
        ...
    }

It's best to call C<validate()> in conjunction with this to make
sure the form validation works. To make sure you're getting accurate
info, it's recommended that you name your forms with the C<name>
option described above.

If you're writing a multiple-form app, you should name your forms
with the C<name> option to ensure that you are getting an accurate
return value from this sub. See the C<name> option above, under
C<render()>.

You can also specify the name of an optional field which you want to
"watch" instead of the default C<_submitted> hidden field. This is useful
if you have a search form and also want to be able to link to it from
other documents directly, such as:

    mysearch.cgi?lookup=what+to+look+for

Normally, C<submitted()> would return false since the C<_submitted>
field is not included. However, you can override this by saying:

    $form->submitted('lookup');

Then, if the lookup field is present, you'll get a true value.
(Actually, you'll still get the value of the "Submit" button if
present.)

=head2 validate()

This validates the form based on the validation criteria passed
into C<new()> via the C<validate> option. In addition, you can
specify additional criteria to check that will be valid for just
that call of C<validate()>. This is useful is you have to deal
with different geos:

    if ($location eq 'US') {
        $form->validate(state => 'STATE', zipcode => 'ZIPCODE');
    } else {
        $form->validate(state => '/^\w{2,3}$/');
    }

You can also provide a L<Data::FormValidator> object as the first
argument. In that case, the second argument (if present) will be
interpreted as the name of the validation profile to use. A single
string argument will also be interpreted as a validation profile
name.

Note that if you pass args to your C<validate()> function like
this, you will not get JavaScript generated or required fields
placed in bold. So, this is good for conditional validation
like the above example, but for most applications you want to
pass your validation requirements in via the C<validate>
option to the C<new()> function, and just call the C<validate()>
function with no arguments.

=head2 confirm()

The purpose of this function is to print out a static confirmation
screen showing a short message along with the values that were
submitted. It is actually just a special wrapper around C<render()>,
twiddling a couple options.

If you're using templates, you probably want to specify a separate
success template, such as:

    if ($form->submitted && $form->validate) {
        print $form->confirm(template => 'success.tmpl');
    } else {
        print $form->render(template => 'fillin.tmpl');
    }

So that you don't get the same screen twice.

=head2 mailconfirm()

This sends a confirmation email to the named addresses. The C<to>
argument is required; everything else is optional. If no C<from>
is specified then it will be set to the address C<auto-reply>
since that is a common quasi-standard in the web app world.

This does not send any of the form results. Rather, it simply
prints out a message saying the submission was received.

=head2 mailresults()

This emails the form results to the specified address(es). By 
default it prints out the form results separated by a colon, such as:

    name: Nate Wiger
    email: nate@wiger.org
    colors: red green blue

And so on. You can change this by specifying the C<delimiter> and
C<joiner> options. For example this:

    $form->mailresults(to => $to, delimiter => '=', joiner => ',');

Would produce an email like this:

    name=Nate Wiger
    email=nate@wiger.org
    colors=red,green,blue

Note that now the last field ("colors") is separated by commas since
you have multiple values and you specified a comma as your C<joiner>.

=head2 mailresults() with plugin

Now you can also specify a plugin to use with mailresults, in
the namespace C<CGI::FormBuilder::Mail::*>.  These plugins may

lib/CGI/FormBuilder.pod  view on Meta::CPAN

=head2 self_url()

This returns a self url, similar to C<CGI.pm>, but again B<ONLY> with
form fields.

=head2 script_name()

An alias for C<< $form->action >>.

=head1 STYLESHEETS (CSS)

If the C<stylesheet> option is enabled (by setting it to 1 or the 
path of a CSS file), then B<FormBuilder> will automatically output
style classes for every single form element:

    fb              main form table
    fb_label        td containing field label
    fb_field        td containing field input tag
    fb_submit       td containing submit button(s)

    fb_input        input types
    fb_select       select types
    fb_checkbox     checkbox types
    fb_radio        radio types
    fb_option       labels for checkbox/radio options
    fb_button       button types
    fb_hidden       hidden types
    fb_static       static types

    fb_required     span around labels for required fields
    fb_invalid      span around labels for invalid fields
    fb_comment      span around field comment
    fb_error        span around field error message

Here's a simple example that you can put in C<fb.css> which spruces
up a couple basic form features:

    /* FormBuilder */
    .fb {
        background: #ffc;
        font-family: verdana,arial,sans-serif;
        font-size: 10pt;
    }

    .fb_label {
        text-align: right;
        padding-right: 1em;
    }

    .fb_comment {
        font-size: 8pt;
        font-style: italic;
    }

    .fb_submit {
        text-align: center;
    }

    .fb_required {
        font-weight: bold;
    }

    .fb_invalid {
        color: #c00;
        font-weight: bold;
    }

    .fb_error {
        color: #c00;
        font-style: italic;
    }

Of course, if you're familiar with CSS, you know a lot more is possible.
Also, you can mess with all the id's (if you name your forms) to
manipulate fields more exactly.

=head1 EXAMPLES

I find this module incredibly useful, so here are even more examples,
pasted from sample code that I've written:

=head2 Ex1: order.cgi

This example provides an order form, complete with validation of the
important fields, and a "Cancel" button to abort the whole thing.

    #!/usr/bin/perl

    use strict;
    use CGI::FormBuilder;

    my @states = my_state_list();   # you write this

    my $form = CGI::FormBuilder->new(
                    method => 'post',
                    fields => [
                        qw(first_name last_name
                           email send_me_emails
                           address state zipcode
                           credit_card expiration)
                    ],

                    header => 1,
                    title  => 'Finalize Your Order',
                    submit => ['Place Order', 'Cancel'],
                    reset  => 0,

                    validate => {
                         email   => 'EMAIL',
                         zipcode => 'ZIPCODE',
                         credit_card => 'CARD',
                         expiration  => 'MMYY',
                    },
                    required => 'ALL',
                    jsfunc => <<EOJS,
    // skip js validation if they clicked "Cancel"
    if (this._submit.value == 'Cancel') return true;
EOJS
               );

    # Provide a list of states
    $form->field(name    => 'state',
                 options => \@states,
                 sortopts=> 'NAME');