view release on metacpan or  search on metacpan

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

=head2 How can I change option XXX based on a conditional?

To change an option, simply use its accessor at any time:

    my $form = CGI::FormBuilder->new(
                    method => 'post',
                    fields => [qw(name email phone)]
               );

    my $mode = $form->cgi_param('mode');

    if ($mode eq 'add') {
        $form->title('Add a new entry');
    } elsif ($mode eq 'edit') {
        $form->title('Edit existing entry');

        # do something to select existing values
        my %values = select_values();

        $form->values(\%values);
    }
    print $form->render;

Using the accessors makes permanent changes to your object, so
be aware that if you want to reset something to its original
value later, you'll have to first save it and then reset it:

    my $style = $form->stylesheet;
    $form->stylesheet(0);       # turn off
    $form->stylesheet($style);  # original setting

You can also specify options to C<render()>, although using the
accessors is the preferred way.

=head2 How do I manually override the value of a field?

You must specify the C<force> option:

    $form->field(name  => 'name_of_field',
                 value => $value,
                 force => 1);

If you don't specify C<force>, then the CGI value will always win.
This is because of the stateless nature of the CGI protocol.

=head2 How do I make it so that the values aren't shown in the form?

Turn off sticky:

    my $form = CGI::FormBuilder->new(... sticky => 0);

By turning off the C<sticky> option, you will still be able to access
the values, but they won't show up in the form.

=head2 I can't get "validate" to accept my regular expressions!

You're probably not specifying them within single quotes. See the
section on C<validate> above.

=head2 Can FormBuilder handle file uploads?

It sure can, and it's really easy too. Just change the C<enctype>
as an option to C<new()>:

    use CGI::FormBuilder;
    my $form = CGI::FormBuilder->new(
                    enctype => 'multipart/form-data',
                    method  => 'post',
                    fields  => [qw(filename)]
               );

    $form->field(name => 'filename', type => 'file');

And then get to your file the same way as C<CGI.pm>:

    if ($form->submitted) {
        my $file = $form->field('filename');

        # save contents in file, etc ...
        open F, ">$dir/$file" or die $!;
        while (<$file>) {
            print F;
        }
        close F;

        print $form->confirm(header => 1);
    } else {
        print $form->render(header => 1);
    }

In fact, that's a whole file upload program right there.

=head1 REFERENCES

This really doesn't belong here, but unfortunately many people are
confused by references in Perl. Don't be - they're not that tricky.
When you take a reference, you're basically turning something into
a scalar value. Sort of. You have to do this if you want to pass
arrays intact into functions in Perl 5.

A reference is taken by preceding the variable with a backslash (\).
In our examples above, you saw something similar to this:

    my @fields = ('name', 'email');   # same as = qw(name email)

    my $form = CGI::FormBuilder->new(fields => \@fields);

Here, C<\@fields> is a reference. Specifically, it's an array
reference, or "arrayref" for short.

Similarly, we can do the same thing with hashes:

    my %validate = (
        name  => 'NAME';
        email => 'EMAIL',
    );

    my $form = CGI::FormBuilder->new( ... validate => \%validate);

Here, C<\%validate> is a hash reference, or "hashref".

Basically, if you don't understand references and are having trouble
wrapping your brain around them, you can try this simple rule: Any time
you're passing an array or hash into a function, you must precede it
with a backslash. Usually that's true for CPAN modules.

Finally, there are two more types of references: anonymous arrayrefs
and anonymous hashrefs. These are created with C<[]> and C<{}>,
respectively. So, for our purposes there is no real difference between
this code:

    my @fields = qw(name email);
    my %validate = (name => 'NAME', email => 'EMAIL');

    my $form = CGI::FormBuilder->new(
                    fields   => \@fields,
                    validate => \%validate
               );

And this code:

    my $form = CGI::FormBuilder->new(
                    fields   => [ qw(name email) ],
                    validate => { name => 'NAME', email => 'EMAIL' }
               );

Except that the latter doesn't require that we first create 
C<@fields> and C<%validate> variables.

=head1 ENVIRONMENT VARIABLES