1CGI::FormBuilder::MultiU(s3e)r Contributed Perl DocumentaCtGiIo:n:FormBuilder::Multi(3)
2
6 CGI::FormBuilder::Multi - Create multi-page FormBuilder forms
7
9 use CGI::FormBuilder::Multi;
10 use CGI::Session; # or something similar
11 # Top-level "meta-form"
13 my $multi = CGI::FormBuilder::Multi->new(
14 # form 1 options
16 { fields => [qw(name email daytime_phone evening_phone)],
17 title => 'Basic Info',
18 template => 'page1.tmpl',
19 validate => { name => 'NAME', email => 'EMAIL' },
20 required => [qw(name email daytime_phone)],
21 },
22 # form 2 options
24 { fields => [qw(billing_name billing_card billing_exp
25 billing_address billing_city billing_state
26 billing_zip billing_phone)],
27 title => 'Billing',
28 template => 'page2.tmpl',
29 required => 'ALL',
30 },
31 # form 3 options
33 { fields => [qw(same_as_billing shipping_address
34 shipping_city shipping_state shipping_zip)],
35 title => 'Shipping',
36 template => 'page3.tmpl',
37 required => 'ALL',
38 },
39 # a couple options specific to this module
41 navbar => 1,
42 # remaining options (not in hashrefs) apply to all forms
44 header => 1,
45 method => 'POST',
46 submit => 'Continue',
47 values => $dbi_hashref_query,
48 );
49 # Get current page's form
51 my $form = $multi->form;
52 if ($form->submitted && $form->validate) {
54 # Retrieve session id
56 my $sid = $form->sessionid;
57 # Initialize session
59 my $session = CGI::Session->new("driver:File", $sid, {Directory=>'/tmp'});
60 # Automatically store updated data in session
62 $session->save_param($form);
63 # last page?
65 if ($multi->page == $multi->pages) {
66 print $form->confirm;
67 exit;
68 }
69 # Still here, goto next page
71 $multi->page++;
72 # And re-get form (no "my" on $form!)
74 $form = $multi->form;
75 # Make sure it has the right sessionid
77 $form->sessionid($session->id);
78 # on page 3 we have special field handling
80 if ($multi->page == 3) {
81 $form->field(name => 'same_as_billing',
82 type => 'checkbox',
83 options => 'Yes',
84 jsclick => 'this.form.submit()');
85 }
86 }
87 # Fall through and print next page's form
89 print $form->render;
90
92 This module works with "CGI::FormBuilder" to create multi-page forms.
93 Each form is specified using the same options you would pass directly
94 into FormBuilder. See CGI::FormBuilder for a list of these options.
95 The multi-page "meta-form" is a composite of the individual forms you
97 specify, tied together via the special "_page" CGI param. The current
98 form is available via the "form()" method, and the current page is
99 available via "page()". It's up to you to navigate appropriately:
100 my $multi = CGI::FormBuilder::Multi->new(...);
102 # current form
104 my $form = $multi->form;
105 $multi->page++; # page forward
107 $multi->page--; # and back
108 $multi->page = $multi->pages; # goto last page
109 # current form
111 $form = $multi->form;
112 To make things are fluid as possible, you should title each of your
114 forms, even if you're using a template. This will allow "::Multi" to
115 create cross-links by-name instead of just "Page 2".
116
118 The following methods are provided:
119 new(\%form1, \%form2, opt => val)
121 This creates a new "CGI::FormBuilder::Multi" object. Forms are
122 specified as hashrefs of options, in sequential order, similar to how
123 fields are specified. The order the forms are in is the order that the
124 pages will cycle through.
125 In addition to a hashref, forms can be directly specified as a $form
127 object that has already been created. For existing objects, the below
128 does not apply.
129 When the first non-ref argument is seen, then all remaining args are
131 taken as common options that apply to all forms. In this way, you can
132 specify global settings for things like "method" or "header" (which
133 will likely be the same), and then override individual settings like
134 "fields" and "validate" on a per-form basis.
135 If you do not wish to specify any options for your forms, you can
137 instead just specify the "pages" option, for example:
138 my $multi = CGI::FormBuilder::Multi->new(pages => 3);
140 With this approach, you will have to dynamically assemble each page as
142 you come to them. The mailing list can help.
143 The "SYNOPSIS" above is very representative of typical usage.
145 form()
147 This returns the current page's form, as an object created directly by
148 "CGI::FormBuilder->new". All valid FormBuilder methods and options work
149 on the form. To change which form is returned, us "page()".
150 page($num)
152 This sets and returns the current page. It can accept a page number
153 either as an argument, or directly as an assignment:
154 $multi->page(1); # page 1
156 $multi->page = 1; # same thing
157 $multi->page++; # next page
159 $multi->page--; # back one
160 if ($multi->page == $multi->pages) {
162 # last page
163 }
164 Hint: Usually, you should only change pages once you have validated the
166 current page's form appropriately.
167 pages()
169 This returns the total number of pages. Actually, what it returns is an
170 array of all forms (and hence it has the alias "forms()"), which just
171 so happens to become the length in a scalar context, just like anywhere
172 else in Perl.
173 navbar($onoff)
175 This returns a navigation bar that allows the user to jump between
176 pages of the form. This is useful if you want to let a person fill out
177 different pages out of order. In most cases, you do not want this, so
178 it's off by default.
179 To use it, the best way is setting "navbar => 1" in "new()". However,
181 you can also get it yourself to render your own HTML:
182 my $html = $multi->navbar; # scalar HTML
184 my @link = $multi->navbar; # array of links
185 This is useful in something like this:
187 my $nav = $multi->navbar;
189 $form = $multi->form;
190 $form->tmpl_param(navbar => $navbar);
191 The navbar will have two style classes: "fb_multi_page" for the current
193 page's link, and "fb_multi_link" for the others.
194
196 CGI::FormBuilder
197
199 $Id: Multi.pm 100 2007-03-02 18:13:13Z nwiger $
200
202 Copyright (c) 2005-2006 Nate Wiger <nate@wiger.org>. All Rights
203 Reserved.
204 This module is free software; you may copy this under the terms of the
206 GNU General Public License, or the Artistic License, copies of which
207 should have accompanied your Perl kit.
208perl v5.12.0 2007-03-02 CGI::FormBuilder::Multi(3)