1CGI::FormBuilder::MultiU(s3e)r Contributed Perl DocumentaCtGiIo:n:FormBuilder::Multi(3)
2
3
4

NAME

6       CGI::FormBuilder::Multi - Create multi-page FormBuilder forms
7

SYNOPSIS

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

DESCRIPTION

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

METHODS

118       The following methods are provided:
119
120   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
126       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
130       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
136       If you do not wish to specify any options for your forms, you can
137       instead just specify the "pages" option, for example:
138
139           my $multi = CGI::FormBuilder::Multi->new(pages => 3);
140
141       With this approach, you will have to dynamically assemble each page as
142       you come to them. The mailing list can help.
143
144       The "SYNOPSIS" above is very representative of typical usage.
145
146   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
151   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
155           $multi->page(1);    # page 1
156           $multi->page = 1;   # same thing
157
158           $multi->page++;     # next page
159           $multi->page--;     # back one
160
161           if ($multi->page == $multi->pages) {
162               # last page
163           }
164
165       Hint: Usually, you should only change pages once you have validated the
166       current page's form appropriately.
167
168   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
174   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
180       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
183           my $html = $multi->navbar;      # scalar HTML
184           my @link = $multi->navbar;      # array of links
185
186       This is useful in something like this:
187
188           my $nav = $multi->navbar;
189           $form = $multi->form;
190           $form->tmpl_param(navbar => $navbar);
191
192       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

SEE ALSO

196       CGI::FormBuilder
197

REVISION

199       $Id: Multi.pm 100 2007-03-02 18:13:13Z nwiger $
200

AUTHOR

202       Copyright (c) 2005-2006 Nate Wiger <nate@wiger.org>. All Rights
203       Reserved.
204
205       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.
208
209
210
211perl v5.12.0                      2007-03-02        CGI::FormBuilder::Multi(3)
Impressum