1CGI::FormBuilder::TemplUasteer::CHoTnMtLr(i3b)uted PerlCDGoIc:u:mFeonrtmaBtuiiolnder::Template::HTML(3)
2
3
4

NAME

6       CGI::FormBuilder::Template::HTML - FormBuilder interface to
7       HTML::Template
8

SYNOPSIS

10           my $form = CGI::FormBuilder->new(
11                           fields   => \@fields,
12                           template => 'form.tmpl',
13                      );
14

DESCRIPTION

16       This engine adapts FormBuilder to use "HTML::Template".
17       "HTML::Template" is the default template option and is activated one of
18       two ways. Either:
19
20           my $form = CGI::FormBuilder->new(
21                           fields => \@fields,
22                           template => 'form.tmpl',
23                      );
24
25       Or, you can specify any options which "HTML::Template->new" accepts by
26       using a hashref:
27
28           my $form = CGI::FormBuilder->new(
29                           fields => \@fields,
30                           template => {
31                               type => 'HTML',
32                               filename => 'form.tmpl',
33                               shared_cache => 1,
34                               loop_context_vars => 1
35                           }
36                       );
37
38       The following methods are provided (usually only used internally):
39
40   engine
41       Returns a reference to the "HTML::Template" object
42
43   prepare
44       Returns a hash of all the fields ready to be rendered.
45
46   render
47       Uses the prepared hash and expands the template, returning a string of
48       HTML.
49

TEMPLATES

51       In your template, each of the form fields will correspond directly to a
52       "<tmpl_var>" of the same name prefixed with "field-" in the template.
53       So, if you defined a field called "email", then you would setup a
54       variable called "<tmpl_var field-email>" in your template.
55
56       In addition, there are a couple special fields:
57
58           <tmpl_var js-head>     -  JavaScript to stick in <head>
59           <tmpl_var form-title>  -  The <title> of the HTML form
60           <tmpl_var form-start>  -  Opening <form> tag and internal fields
61           <tmpl_var form-submit> -  The submit button(s)
62           <tmpl_var form-reset>  -  The reset button
63           <tmpl_var form-end>    -  Just the closing </form> tag
64
65       Let's look at an example "form.tmpl" template we could use:
66
67           <html>
68           <head>
69           <title>User Information</title>
70           <tmpl_var js-head><!-- this holds the JavaScript code -->
71           </head>
72           <tmpl_var form-start><!-- this holds the initial form tag -->
73           <h3>User Information</h3>
74           Please fill out the following information:
75           <!-- each of these tmpl_var's corresponds to a field -->
76           <p>Your full name: <tmpl_var field-name>
77           <p>Your email address: <tmpl_var field-email>
78           <p>Choose a password: <tmpl_var field-password>
79           <p>Please confirm it: <tmpl_var field-confirm_password>
80           <p>Your home zipcode: <tmpl_var field-zipcode>
81           <p>
82           <tmpl_var form-submit><!-- this holds the form submit button -->
83           </form><!-- can also use "tmpl_var form-end", same thing -->
84
85       As you see, you get a "<tmpl_var>" for each for field you define.
86
87       However, you may want even more control. That is, maybe you want to
88       specify every nitty-gritty detail of your input fields, and just want
89       this module to take care of the statefulness of the values. This is no
90       problem, since this module also provides several other "<tmpl_var>"
91       tags as well:
92
93           <tmpl_var value-[field]>   - The value of a given field
94           <tmpl_var label-[field]>   - The human-readable label
95           <tmpl_var comment-[field]> - Any optional comment
96           <tmpl_var error-[field]>   - Error text if validation fails
97           <tmpl_var required-[field]> - See if the field is required
98
99       This means you could say something like this in your template:
100
101           <tmpl_var label-email>:
102           <input type="text" name="email" value="<tmpl_var value-email>">
103           <font size="-1"><i><tmpl_var error-email></i></font>
104
105       And FormBuilder would take care of the value stickiness for you, while
106       you have control over the specifics of the "<input>" tag.  A sample
107       expansion may create HTML like the following:
108
109           Email:
110           <input type="text" name="email" value="nate@wiger.org">
111           <font size="-1"><i>You must enter a valid value</i></font>
112
113       Note, though, that this will only get the first value in the case of a
114       multi-value parameter (for example, a multi-select list). To remedy
115       this, if there are multiple values you will also get a "<tmpl_var>"
116       prefixed with "loop-". So, if you had:
117
118           myapp.cgi?color=gray&color=red&color=blue
119
120       This would give the "color" field three values. To create a select
121       list, you would do this in your template:
122
123           <select name="color" multiple>
124           <tmpl_loop loop-color>
125               <option value="<tmpl_var value>"><tmpl_var label></option>
126           </tmpl_loop>
127           </select>
128
129       With "<tmpl_loop>" tags, each iteration gives you several variables:
130
131           Inside <tmpl_loop>, this...  Gives you this
132           ---------------------------  -------------------------------
133           <tmpl_var value>             value of that option
134           <tmpl_var label>             label for that option
135           <tmpl_var checked>           if selected, the word "checked"
136           <tmpl_var selected>          if selected, the word "selected"
137
138       Please note that "<tmpl_var value>" gives you one of the options, not
139       the values. Why? Well, if you think about it you'll realize that select
140       lists and radio groups are fundamentally different from input boxes in
141       a number of ways. Whereas in input tags you can just have an empty
142       value, with lists you need to iterate through each option and then
143       decide if it's selected or not.
144
145       When you need precise control in a template this is all exposed to you;
146       normally FormBuilder does all this magic for you. If you don't need
147       exact control over your lists, simply use the "<tmpl_var field-[name]>"
148       tag and this will all be done automatically, which I strongly
149       recommend.
150
151       But, let's assume you need exact control over your lists. Here's an
152       example select list template:
153
154           <select name="color" multiple>
155           <tmpl_loop loop-color>
156           <option value="<tmpl_var value>" <tmpl_var selected>><tmpl_var label>
157           </tmpl_loop>
158           </select>
159
160       Then, your Perl code would fiddle the field as follows:
161
162           $form->field(
163                     name => 'color', nameopts => 1,
164                     options => [qw(red green blue yellow black white gray)]
165                  );
166
167       Assuming query string as shown above, the template would then be
168       expanded to something like this:
169
170           <select name="color" multiple>
171           <option value="red" selected>Red
172           <option value="green" >Green
173           <option value="blue" selected>Blue
174           <option value="yellow" >Yellow
175           <option value="black" >Black
176           <option value="white" >White
177           <option value="gray" selected>Gray
178           </select>
179
180       Notice that the "<tmpl_var selected>" tag is expanded to the word
181       "selected" when a given option is present as a value as well (i.e., via
182       the CGI query). The "<tmpl_var value>" tag expands to each option in
183       turn, and "<tmpl_var label>" is expanded to the label for that value.
184       In this case, since "nameopts" was specified to "field()", the labels
185       are automatically generated from the options.
186
187       Let's look at one last example. Here we want a radio group that allows
188       a person to remove themself from a mailing list. Here's our template:
189
190           Do you want to be on our mailing list?
191           <p><table>
192           <tmpl_loop loop-mailopt>
193           <td bgcolor="silver">
194             <input type="radio" name="mailopt" value="<tmpl_var value>">
195           </td>
196           <td bgcolor="white"><tmpl_var label></td>
197           </tmpl_loop>
198           </table>
199
200       Then, we would twiddle our "mailopt" field via "field()":
201
202           $form->field(
203                     name => 'mailopt',
204                     options => [
205                        [ 1 => 'Yes, please keep me on it!' ],
206                        [ 0 => 'No, remove me immediately.' ]
207                     ]
208                  );
209
210       When the template is rendered, the result would be something like this:
211
212           Do you want to be on our mailing list?
213           <p><table>
214
215           <td bgcolor="silver">
216             <input type="radio" name="mailopt" value="1">
217           </td>
218           <td bgcolor="white">Yes, please keep me on it!</td>
219
220           <td bgcolor="silver">
221             <input type="radio" name="mailopt" value="0">
222           </td>
223           <td bgcolor="white">No, remove me immediately</td>
224
225           </table>
226
227       When the form was then sumbmitted, you would access the values just
228       like any other field:
229
230           if ($form->field('mailopt')) {
231               # is 1, so add them
232           } else {
233               # is 0, remove them
234           }
235
236       Finally, you can also loop through each of the fields using the top-
237       level "fields" loop in your template. This allows you to reuse the same
238       template even if your parameters change. The following template code
239       would loop through each field, creating a table row for each:
240
241           <table>
242           <tmpl_loop fields>
243           <tr>
244           <td class="small"><tmpl_if required><b><tmpl_var label></b><tmpl_else><tmpl_var label></tmpl_if></td>
245           <td><tmpl_var field></td>
246           </tr>
247           </tmpl_loop>
248           </table>
249
250       Each loop will have a "label", "field", "value", etc, just like above.
251
252       For more information on templates, see HTML::Template.
253

SEE ALSO

255       CGI::FormBuilder, CGI::FormBuilder::Template, HTML::Template
256

REVISION

258       $Id: HTML.pm 100 2007-03-02 18:13:13Z nwiger $
259

AUTHOR

261       Copyright (c) 2000-2006 Nate Wiger <nate@wiger.org>. All Rights
262       Reserved.
263
264       This module is free software; you may copy this under the terms of the
265       GNU General Public License, or the Artistic License, copies of which
266       should have accompanied your Perl kit.
267
268
269
270perl v5.12.0                      2007-03-02CGI::FormBuilder::Template::HTML(3)
Impressum