1CGI::FormBuilder::TemplUasteer::CHoTnMtLr(i3b)uted PerlCDGoIc:u:mFeonrtmaBtuiiolnder::Template::HTML(3)
2
6 CGI::FormBuilder::Template::HTML - FormBuilder interface to HTML::Tem‐
7 plate
8
10 my $form = CGI::FormBuilder->new(
11 fields => \@fields,
12 template => 'form.tmpl',
13 );
14
16 This engine adapts FormBuilder to use "HTML::Template". "HTML::Tem‐
17 plate" is the default template option and is activated one of two ways.
18 Either:
19 my $form = CGI::FormBuilder->new(
21 fields => \@fields,
22 template => 'form.tmpl',
23 );
24 Or, you can specify any options which "HTML::Template->new" accepts by
26 using a hashref:
27 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 The following methods are provided (usually only used internally):
39 engine
41 Returns a reference to the "HTML::Template" object
43 prepare
45 Returns a hash of all the fields ready to be rendered.
47 render
49 Uses the prepared hash and expands the template, returning a string of
51 HTML.
52
54 In your template, each of the form fields will correspond directly to a
55 "<tmpl_var>" of the same name prefixed with "field-" in the template.
56 So, if you defined a field called "email", then you would setup a vari‐
57 able called "<tmpl_var field-email>" in your template.
58 In addition, there are a couple special fields:
60 <tmpl_var js-head> - JavaScript to stick in <head>
62 <tmpl_var form-title> - The <title> of the HTML form
63 <tmpl_var form-start> - Opening <form> tag and internal fields
64 <tmpl_var form-submit> - The submit button(s)
65 <tmpl_var form-reset> - The reset button
66 <tmpl_var form-end> - Just the closing </form> tag
67 Let's look at an example "form.tmpl" template we could use:
69 <html>
71 <head>
72 <title>User Information</title>
73 <tmpl_var js-head><!-- this holds the JavaScript code -->
74 </head>
75 <tmpl_var form-start><!-- this holds the initial form tag -->
76 <h3>User Information</h3>
77 Please fill out the following information:
78 <!-- each of these tmpl_var's corresponds to a field -->
79 <p>Your full name: <tmpl_var field-name>
80 <p>Your email address: <tmpl_var field-email>
81 <p>Choose a password: <tmpl_var field-password>
82 <p>Please confirm it: <tmpl_var field-confirm_password>
83 <p>Your home zipcode: <tmpl_var field-zipcode>
84 <p>
85 <tmpl_var form-submit><!-- this holds the form submit button -->
86 </form><!-- can also use "tmpl_var form-end", same thing -->
87 As you see, you get a "<tmpl_var>" for each for field you define.
89 However, you may want even more control. That is, maybe you want to
91 specify every nitty-gritty detail of your input fields, and just want
92 this module to take care of the statefulness of the values. This is no
93 problem, since this module also provides several other "<tmpl_var>"
94 tags as well:
95 <tmpl_var value-[field]> - The value of a given field
97 <tmpl_var label-[field]> - The human-readable label
98 <tmpl_var comment-[field]> - Any optional comment
99 <tmpl_var error-[field]> - Error text if validation fails
100 <tmpl_var required-[field]> - See if the field is required
101 This means you could say something like this in your template:
103 <tmpl_var label-email>:
105 <input type="text" name="email" value="<tmpl_var value-email>">
106 <font size="-1"><i><tmpl_var error-email></i></font>
107 And FormBuilder would take care of the value stickiness for you, while
109 you have control over the specifics of the "<input>" tag. A sample
110 expansion may create HTML like the following:
111 Email:
113 <input type="text" name="email" value="nate@wiger.org">
114 <font size="-1"><i>You must enter a valid value</i></font>
115 Note, though, that this will only get the first value in the case of a
117 multi-value parameter (for example, a multi-select list). To remedy
118 this, if there are multiple values you will also get a "<tmpl_var>"
119 prefixed with "loop-". So, if you had:
120 myapp.cgi?color=gray&color=red&color=blue
122 This would give the "color" field three values. To create a select
124 list, you would do this in your template:
125 <select name="color" multiple>
127 <tmpl_loop loop-color>
128 <option value="<tmpl_var value>"><tmpl_var label></option>
129 </tmpl_loop>
130 </select>
131 With "<tmpl_loop>" tags, each iteration gives you several variables:
133 Inside <tmpl_loop>, this... Gives you this
135 --------------------------- -------------------------------
136 <tmpl_var value> value of that option
137 <tmpl_var label> label for that option
138 <tmpl_var checked> if selected, the word "checked"
139 <tmpl_var selected> if selected, the word "selected"
140 Please note that "<tmpl_var value>" gives you one of the options, not
142 the values. Why? Well, if you think about it you'll realize that select
143 lists and radio groups are fundamentally different from input boxes in
144 a number of ways. Whereas in input tags you can just have an empty
145 value, with lists you need to iterate through each option and then
146 decide if it's selected or not.
147 When you need precise control in a template this is all exposed to you;
149 normally FormBuilder does all this magic for you. If you don't need
150 exact control over your lists, simply use the "<tmpl_var field-[name]>"
151 tag and this will all be done automatically, which I strongly recom‐
152 mend.
153 But, let's assume you need exact control over your lists. Here's an
155 example select list template:
156 <select name="color" multiple>
158 <tmpl_loop loop-color>
159 <option value="<tmpl_var value>" <tmpl_var selected>><tmpl_var label>
160 </tmpl_loop>
161 </select>
162 Then, your Perl code would fiddle the field as follows:
164 $form->field(
166 name => 'color', nameopts => 1,
167 options => [qw(red green blue yellow black white gray)]
168 );
169 Assuming query string as shown above, the template would then be
171 expanded to something like this:
172 <select name="color" multiple>
174 <option value="red" selected>Red
175 <option value="green" >Green
176 <option value="blue" selected>Blue
177 <option value="yellow" >Yellow
178 <option value="black" >Black
179 <option value="white" >White
180 <option value="gray" selected>Gray
181 </select>
182 Notice that the "<tmpl_var selected>" tag is expanded to the word
184 "selected" when a given option is present as a value as well (i.e., via
185 the CGI query). The "<tmpl_var value>" tag expands to each option in
186 turn, and "<tmpl_var label>" is expanded to the label for that value.
187 In this case, since "nameopts" was specified to "field()", the labels
188 are automatically generated from the options.
189 Let's look at one last example. Here we want a radio group that allows
191 a person to remove themself from a mailing list. Here's our template:
192 Do you want to be on our mailing list?
194 <p><table>
195 <tmpl_loop loop-mailopt>
196 <td bgcolor="silver">
197 <input type="radio" name="mailopt" value="<tmpl_var value>">
198 </td>
199 <td bgcolor="white"><tmpl_var label></td>
200 </tmpl_loop>
201 </table>
202 Then, we would twiddle our "mailopt" field via "field()":
204 $form->field(
206 name => 'mailopt',
207 options => [
208 [ 1 => 'Yes, please keep me on it!' ],
209 [ 0 => 'No, remove me immediately.' ]
210 ]
211 );
212 When the template is rendered, the result would be something like this:
214 Do you want to be on our mailing list?
216 <p><table>
217 <td bgcolor="silver">
219 <input type="radio" name="mailopt" value="1">
220 </td>
221 <td bgcolor="white">Yes, please keep me on it!</td>
222 <td bgcolor="silver">
224 <input type="radio" name="mailopt" value="0">
225 </td>
226 <td bgcolor="white">No, remove me immediately</td>
227 </table>
229 When the form was then sumbmitted, you would access the values just
231 like any other field:
232 if ($form->field('mailopt')) {
234 # is 1, so add them
235 } else {
236 # is 0, remove them
237 }
238 Finally, you can also loop through each of the fields using the top-
240 level "fields" loop in your template. This allows you to reuse the same
241 template even if your parameters change. The following template code
242 would loop through each field, creating a table row for each:
243 <table>
245 <tmpl_loop fields>
246 <tr>
247 <td class="small"><tmpl_if required><b><tmpl_var label></b><tmpl_else><tmpl_var label></tmpl_if></td>
248 <td><tmpl_var field></td>
249 </tr>
250 </tmpl_loop>
251 </table>
252 Each loop will have a "label", "field", "value", etc, just like above.
254 For more information on templates, see HTML::Template.
256
258 CGI::FormBuilder, CGI::FormBuilder::Template, HTML::Template
259
261 $Id: HTML.pm 100 2007-03-02 18:13:13Z nwiger $
262
264 Copyright (c) 2000-2006 Nate Wiger <nate@wiger.org>. All Rights
265 Reserved.
266 This module is free software; you may copy this under the terms of the
268 GNU General Public License, or the Artistic License, copies of which
269 should have accompanied your Perl kit.
270perl v5.8.8 2007-03-02CGI::FormBuilder::Template::HTML(3)