1CGI::FormBuilder::TemplUasteer::CToenxttr(i3b)uted PerlCDGoIc:u:mFeonrtmaBtuiiolnder::Template::Text(3)
2
6 CGI::FormBuilder::Template::Text - FormBuilder interface to Text::Tem‐
7 plate
8
10 my $form = CGI::FormBuilder->new(
11 fields => \@fields,
12 template => {
13 type => 'Text',
14 template => 'form.tmpl',
15 variable => 'form',
16 }
17 );
18
20 This engine adapts FormBuilder to use "Text::Template". Usage is very
21 similar to Template Toolkit:
22 my $form = CGI::FormBuilder->new(
24 fields => \@fields,
25 template => {
26 type => 'Text', # use Text::Template
27 template => 'form.tmpl',
28 }
29 );
30 The default options passed into "Text::Template->new()" with this call‐
32 ing form are:
33 TYPE => 'FILE'
35 SOURCE => 'form.tmpl'
36 DELIMITERS => ['<%','%>']
37 As these params are passed for you, your template will look very simi‐
39 lar to ones used by Template Toolkit and "HTML::Mason" (the Text::Tem‐
40 plate default delimiters are "{" and "}", but using alternative delim‐
41 iters speeds it up by about 25%, and the "<%" and "%>" delimiters are
42 good, familiar-looking alternatives).
43 The following methods are provided (usually only used internally):
45 engine
47 Returns a reference to the "Text::Template" object
49 prepare
51 Returns a hash of all the fields ready to be rendered.
53 render
55 Uses the prepared hash and expands the template, returning a string of
57 HTML.
58
60 <% $jshead %> - JavaScript to stick in <head>
61 <% $title %> - The <title> of the HTML form
62 <% $start %> - Opening <form> tag and internal fields
63 <% $submit %> - The submit button(s)
64 <% $reset %> - The reset button
65 <% $end %> - Closing </form> tag
66 <% $fields %> - List of fields
67 <% $field %> - Hash of fields (for lookup by name)
68 Note that you refer to variables with a preceding "$", just like in
70 Perl. Like Template Toolkit, you can specify a variable to place
71 fields under:
72 my $form = CGI::FormBuilder->new(
74 fields => \@fields,
75 template => {
76 type => 'Text',
77 template => 'form.tmpl',
78 variable => 'form'
79 },
80 );
81 Unlike Template Toolkit, though, these will not be placed in OO-style,
83 dot-separated vars. Instead, a hash will be created which you then ref‐
84 erence:
85 <% $form{jshead} %>
87 <% $form{start} %>
88 etc.
89 And field data is in a hash-of-hashrefs format:
91 For a field named... The field data is in...
93 -------------------- -----------------------
94 job <% $form{field}{job} %]
95 size <% $form{field}{size} %]
96 email <% $form{field}{email} %]
97 Since "Text::Template" looks so much like Perl, you can access individ‐
99 ual elements and create variables like so:
100 <%
102 my $myfield = $form{field}{email};
103 $myfield->{label}; # text label
104 $myfield->{field}; # field input tag
105 $myfield->{value}; # first value
106 $myfield->{values}; # list of all values
107 $myfield->{options}; # list of all options
108 $myfield->{required}; # required flag
109 $myfield->{invalid}; # invalid flag
110 $myfield->{error}; # error string if invalid
111 %>
112 <%
114 for my $field (@{$form{fields}}) {
115 $OUT .= "<tr>\n<td>" . $field->{label} . "</td> <td>"
116 . $field->{field} . "</td>\n<tr>";
117 }
118 %>
119 In addition, when using the engine option, you supply an existing
121 Text::Template object or a hash of parameters to be passed to "new()".
122 For example, you can ask for different delimiters yourself:
123 my $form = CGI::FormBuilder->new(
125 fields => \@fields,
126 template => {
127 type => 'Text',
128 template => 'form.tmpl',
129 variable => 'form',
130 engine => {
131 DELIMITERS => [ '[@--', '--@]' ],
132 },
133 data => {
134 version => 1.23,
135 author => 'Fred Smith',
136 },
137 },
138 );
139 If you pass a hash of parameters, you can override the "TYPE" and
141 "SOURCE" parameters, as well as any other "Text::Template" options. For
142 example, you can pass in a string template with "TYPE => STRING"
143 instead of loading it from a file. You must specify both "TYPE" and
144 "SOURCE" if doing so. The good news is this is trivial:
145 my $form = CGI::FormBuilder->new(
147 fields => \@fields,
148 template => {
149 type => 'Text',
150 variable => 'form',
151 engine => {
152 TYPE => 'STRING',
153 SOURCE => $string,
154 DELIMITERS => [ '[@--', '--@]' ],
155 },
156 data => {
157 version => 1.23,
158 author => 'Fred Smith',
159 },
160 },
161 );
162 If you get the crazy idea to let users of your application pick the
164 template file (strongly discouraged) and you're getting errors, look at
165 the "Text::Template" documentation for the "UNTAINT" feature.
166 Also, note that "Text::Template"'s "PREPEND => 'use strict;'" option is
168 not recommended due to the dynamic nature for "FormBuilder". If you
169 use it, then you'll have to declare each variable that "FormBuilder"
170 puts into your template with "use vars qw($jshead' ... etc);"
171 If you're really stuck on this, though, a workaround is to say:
173 PREPEND => 'use strict; use vars qw(%form);'
175 and then set the option "variable => 'form'". That way you can have
177 strict Perl without too much hassle, except that your code might be
178 exhausting to look at :-). Things like
179 $form{field}{your_field_name}{field} end up being all over the place,
180 instead of the nicer short forms.
181 Finally, when you use the "data" template option, the keys you specify
183 will be available to the template as regular variables. In the above
184 example, these would be "<% $version %>" and "<% $author %>". And com‐
185 plex datatypes are easy:
186 data => {
188 anArray => [ 1, 2, 3 ],
189 aHash => { orange => 'tangy', chocolate => 'sweet' },
190 }
191 This becomes the following in your template:
193 <%
195 @anArray; # you can use $myArray[1] etc.
196 %aHash; # you can use $myHash{chocolate} etc.
197 %>
198 For more information, please consult the "Text::Template" documenta‐
200 tion.
201
203 CGI::FormBuilder, CGI::FormBuilder::Template, Text::Template
204
206 $Id: Text.pm 100 2007-03-02 18:13:13Z nwiger $
207
209 Copyright (c) 2000-2006 Nate Wiger <nate@wiger.org>. All Rights
210 Reserved.
211 Text::Template support is due to huge contributions by Jonathan Buha‐
213 coff. Thanks man.
214 This module is free software; you may copy this under the terms of the
216 GNU General Public License, or the Artistic License, copies of which
217 should have accompanied your Perl kit.
218perl v5.8.8 2007-03-02CGI::FormBuilder::Template::Text(3)