CGI::FormBuilder::Multi - Create multi-page FormBuilder forms
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;
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.
CGI::FormBuilder
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:
_page
form()
page()
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".
::Multi
The following methods are provided:
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.
CGI::FormBuilder::Multi
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.
$form
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.
method
header
fields
validate
The "SYNOPSIS" above is very representative of typical usage.
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().
CGI::FormBuilder->new
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.
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.
forms()
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:
navbar => 1
new()
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.
fb_multi_page
fb_multi_link
$Id: Multi.pm,v 1.8 2005/03/09 18:43:23 nwiger Exp $
Copyright (c) 2005 Nathan Wiger <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.