1CGI::FormBuilder::MultiU(s3e)r Contributed Perl DocumentaCtGiIo:n:FormBuilder::Multi(3)
2
3
4
6 CGI::FormBuilder::Multi - Create multi-page FormBuilder forms
7
9 use CGI::FormBuilder::Multi;
10 use CGI::Session; # or something similar
11
12 # Top-level "meta-form"
13 my $multi = CGI::FormBuilder::Multi->new(
14
15 # 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
23 # 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
32 # 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
40 # a couple options specific to this module
41 navbar => 1,
42
43 # 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
50 # Get current page's form
51 my $form = $multi->form;
52
53 if ($form->submitted && $form->validate) {
54
55 # Retrieve session id
56 my $sid = $form->sessionid;
57
58 # Initialize session
59 my $session = CGI::Session->new("driver:File", $sid, {Directory=>'/tmp'});
60
61 # Automatically store updated data in session
62 $session->save_param($form);
63
64 # last page?
65 if ($multi->page == $multi->pages) {
66 print $form->confirm;
67 exit;
68 }
69
70 # Still here, goto next page
71 $multi->page++;
72
73 # And re-get form (no "my" on $form!)
74 $form = $multi->form;
75
76 # Make sure it has the right sessionid
77 $form->sessionid($session->id);
78
79 # 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
88 # 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
96 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
101 my $multi = CGI::FormBuilder::Multi->new(...);
102
103 # current form
104 my $form = $multi->form;
105
106 $multi->page++; # page forward
107 $multi->page--; # and back
108 $multi->page = $multi->pages; # goto last page
109
110 # current form
111 $form = $multi->form;
112
113 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
120 new(\%form1, \%form2, opt => val)
121
122 This creates a new "CGI::FormBuilder::Multi" object. Forms are speciā
123 fied as hashrefs of options, in sequential order, similar to how fields
124 are specified. The order the forms are in is the order that the pages
125 will cycle through.
126
127 In addition to a hashref, forms can be directly specified as a $form
128 object that has already been created. For existing objects, the below
129 does not apply.
130
131 When the first non-ref argument is seen, then all remaining args are
132 taken as common options that apply to all forms. In this way, you can
133 specify global settings for things like "method" or "header" (which
134 will likely be the same), and then override individual settings like
135 "fields" and "validate" on a per-form basis.
136
137 If you do not wish to specify any options for your forms, you can
138 instead just specify the "pages" option, for example:
139
140 my $multi = CGI::FormBuilder::Multi->new(pages => 3);
141
142 With this approach, you will have to dynamically assemble each page as
143 you come to them. The mailing list can help.
144
145 The "SYNOPSIS" above is very representative of typical usage.
146
147 form()
148
149 This returns the current page's form, as an object created directly by
150 "CGI::FormBuilder->new". All valid FormBuilder methods and options work
151 on the form. To change which form is returned, us "page()".
152
153 page($num)
154
155 This sets and returns the current page. It can accept a page number
156 either as an argument, or directly as an assignment:
157
158 $multi->page(1); # page 1
159 $multi->page = 1; # same thing
160
161 $multi->page++; # next page
162 $multi->page--; # back one
163
164 if ($multi->page == $multi->pages) {
165 # last page
166 }
167
168 Hint: Usually, you should only change pages once you have validated the
169 current page's form appropriately.
170
171 pages()
172
173 This returns the total number of pages. Actually, what it returns is an
174 array of all forms (and hence it has the alias "forms()"), which just
175 so happens to become the length in a scalar context, just like anywhere
176 else in Perl.
177
178 navbar($onoff)
179
180 This returns a navigation bar that allows the user to jump between
181 pages of the form. This is useful if you want to let a person fill out
182 different pages out of order. In most cases, you do not want this, so
183 it's off by default.
184
185 To use it, the best way is setting "navbar => 1" in "new()". However,
186 you can also get it yourself to render your own HTML:
187
188 my $html = $multi->navbar; # scalar HTML
189 my @link = $multi->navbar; # array of links
190
191 This is useful in something like this:
192
193 my $nav = $multi->navbar;
194 $form = $multi->form;
195 $form->tmpl_param(navbar => $navbar);
196
197 The navbar will have two style classes: "fb_multi_page" for the current
198 page's link, and "fb_multi_link" for the others.
199
201 CGI::FormBuilder
202
204 $Id: Multi.pm 100 2007-03-02 18:13:13Z nwiger $
205
207 Copyright (c) 2005-2006 Nate Wiger <nate@wiger.org>. All Rights
208 Reserved.
209
210 This module is free software; you may copy this under the terms of the
211 GNU General Public License, or the Artistic License, copies of which
212 should have accompanied your Perl kit.
213
214
215
216perl v5.8.8 2007-03-02 CGI::FormBuilder::Multi(3)