CGI::FormBuilder::MultUser Contributed Perl DocumentCGI::FormBuilder::Multi(3)NAMECGI::FormBuilder::Multi - Create multi-page FormBuilder forms
SYNOPSIS
use CGI::FormBuilder::Multi;
use CGI::Session; # or something similar
# Top-level "meta-form"
my $multi = CGI::FormBuilder::Multi->new(
# form 1 options
{ fields => [qw(name email daytime_phone evening_phone)],
title => 'Basic Info',
template => 'page1.tmpl',
validate => { name => 'NAME', email => 'EMAIL' },
required => [qw(name email daytime_phone)],
},
# form 2 options
{ fields => [qw(billing_name billing_card billing_exp
billing_address billing_city billing_state
billing_zip billing_phone)],
title => 'Billing',
template => 'page2.tmpl',
required => 'ALL',
},
# form 3 options
{ fields => [qw(same_as_billing shipping_address
shipping_city shipping_state shipping_zip)],
title => 'Shipping',
template => 'page3.tmpl',
required => 'ALL',
},
# a couple options specific to this module
navbar => 1,
# remaining options (not in hashrefs) apply to all forms
header => 1,
method => 'POST',
submit => 'Continue',
values => $dbi_hashref_query,
);
# Get current page's form
my $form = $multi->form;
if ($form->submitted && $form->validate) {
# Retrieve session id
my $sid = $form->sessionid;
# Initialize session
my $session = CGI::Session->new("driver:File", $sid, {Directory=>'/tmp'});
# Automatically store updated data in session
$session->save_param($form);
# last page?
if ($multi->page == $multi->pages) {
print $form->confirm;
exit;
}
# Still here, goto next page
$multi->page++;
# And re-get form (no "my" on $form!)
$form = $multi->form;
# Make sure it has the right sessionid
$form->sessionid($session->id);
# on page 3 we have special field handling
if ($multi->page == 3) {
$form->field(name => 'same_as_billing',
type => 'checkbox',
options => 'Yes',
jsclick => 'this.form.submit()');
}
}
# Fall through and print next page's form
print $form->render;
DESCRIPTION
This module works with "CGI::FormBuilder" to create multi-page forms.
Each form is specified using the same options you would pass directly
into FormBuilder. See CGI::FormBuilder for a list of these options.
The multi-page "meta-form" is a composite of the individual forms you
specify, tied together via the special "_page" CGI param. The current
form is available via the "form()" method, and the current page is
available via "page()". It's up to you to navigate appropriately:
my $multi = CGI::FormBuilder::Multi->new(...);
# current form
my $form = $multi->form;
$multi->page++; # page forward
$multi->page--; # and back
$multi->page = $multi->pages; # goto last page
# current form
$form = $multi->form;
To make things are fluid as possible, you should title each of your
forms, even if you're using a template. This will allow "::Multi" to
create cross-links by-name instead of just "Page 2".
METHODS
The following methods are provided:
new(\%form1, \%form2, opt => val)
This creates a new "CGI::FormBuilder::Multi" object. Forms are
specified as hashrefs of options, in sequential order, similar to how
fields are specified. The order the forms are in is the order that the
pages will cycle through.
In addition to a hashref, forms can be directly specified as a $form
object that has already been created. For existing objects, the below
does not apply.
When the first non-ref argument is seen, then all remaining args are
taken as common options that apply to all forms. In this way, you can
specify global settings for things like "method" or "header" (which
will likely be the same), and then override individual settings like
"fields" and "validate" on a per-form basis.
If you do not wish to specify any options for your forms, you can
instead just specify the "pages" option, for example:
my $multi = CGI::FormBuilder::Multi->new(pages => 3);
With this approach, you will have to dynamically assemble each page as
you come to them. The mailing list can help.
The "SYNOPSIS" above is very representative of typical usage.
form()
This returns the current page's form, as an object created directly by
"CGI::FormBuilder->new". All valid FormBuilder methods and options work
on the form. To change which form is returned, us "page()".
page($num)
This sets and returns the current page. It can accept a page number
either as an argument, or directly as an assignment:
$multi->page(1); # page 1
$multi->page = 1; # same thing
$multi->page++; # next page
$multi->page--; # back one
if ($multi->page == $multi->pages) {
# last page
}
Hint: Usually, you should only change pages once you have validated the
current page's form appropriately.
pages()
This returns the total number of pages. Actually, what it returns is an
array of all forms (and hence it has the alias "forms()"), which just
so happens to become the length in a scalar context, just like anywhere
else in Perl.
navbar($onoff)
This returns a navigation bar that allows the user to jump between
pages of the form. This is useful if you want to let a person fill out
different pages out of order. In most cases, you do not want this, so
it's off by default.
To use it, the best way is setting "navbar => 1" in "new()". However,
you can also get it yourself to render your own HTML:
my $html = $multi->navbar; # scalar HTML
my @link = $multi->navbar; # array of links
This is useful in something like this:
my $nav = $multi->navbar;
$form = $multi->form;
$form->tmpl_param(navbar => $navbar);
The navbar will have two style classes: "fb_multi_page" for the current
page's link, and "fb_multi_link" for the others.
SEE ALSO
CGI::FormBuilder
REVISION
$Id: Multi.pm 100 2007-03-02 18:13:13Z nwiger $
AUTHOR
Copyright (c) 2005-2006 Nate Wiger <nate@wiger.org>. 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.
perl v5.14.1 2007-03-02 CGI::FormBuilder::Multi(3)
