1CGI::FormBuilder::TemplUasteer::CHoTnMtLr(i3b)uted PerlCDGoIc:u:mFeonrtmaBtuiiolnder::Template::HTML(3)
2
6 CGI::FormBuilder::Template::HTML - FormBuilder interface to
7 HTML::Template
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".
17 "HTML::Template" is the default template option and is activated one of
18 two ways. 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
42 prepare
44 Returns a hash of all the fields ready to be rendered.
45 render
47 Uses the prepared hash and expands the template, returning a string of
48 HTML.
49
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 In addition, there are a couple special fields:
57 <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 Let's look at an example "form.tmpl" template we could use:
66 <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 As you see, you get a "<tmpl_var>" for each for field you define.
86 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 <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 This means you could say something like this in your template:
100 <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 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 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 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 myapp.cgi?color=gray&color=red&color=blue
119 This would give the "color" field three values. To create a select
121 list, you would do this in your template:
122 <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 With "<tmpl_loop>" tags, each iteration gives you several variables:
130 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 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 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 But, let's assume you need exact control over your lists. Here's an
152 example select list template:
153 <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 Then, your Perl code would fiddle the field as follows:
161 $form->field(
163 name => 'color', nameopts => 1,
164 options => [qw(red green blue yellow black white gray)]
165 );
166 Assuming query string as shown above, the template would then be
168 expanded to something like this:
169 <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 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 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 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 Then, we would twiddle our "mailopt" field via "field()":
201 $form->field(
203 name => 'mailopt',
204 options => [
205 [ 1 => 'Yes, please keep me on it!' ],
206 [ 0 => 'No, remove me immediately.' ]
207 ]
208 );
209 When the template is rendered, the result would be something like this:
211 Do you want to be on our mailing list?
213 <p><table>
214 <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 <td bgcolor="silver">
221 <input type="radio" name="mailopt" value="0">
222 </td>
223 <td bgcolor="white">No, remove me immediately</td>
224 </table>
226 When the form was then sumbmitted, you would access the values just
228 like any other field:
229 if ($form->field('mailopt')) {
231 # is 1, so add them
232 } else {
233 # is 0, remove them
234 }
235 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 <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 Each loop will have a "label", "field", "value", etc, just like above.
251 For more information on templates, see HTML::Template.
253
255 CGI::FormBuilder, CGI::FormBuilder::Template, HTML::Template
256
258 $Id: HTML.pm 100 2007-03-02 18:13:13Z nwiger $
259
261 Copyright (c) 2000-2006 Nate Wiger <nate@wiger.org>. All Rights
262 Reserved.
263 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.
267perl v5.12.0 2007-03-02CGI::FormBuilder::Template::HTML(3)