1CGI::FormBuilder::TemplUasteer::CToenxttr(i3b)uted PerlCDGoIc:u:mFeonrtmaBtuiiolnder::Template::Text(3)
2
6 CGI::FormBuilder::Template::Text - FormBuilder interface to
7 Text::Template
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
32 calling form are:
33 TYPE => 'FILE'
35 SOURCE => 'form.tmpl'
36 DELIMITERS => ['<%','%>']
37 As these params are passed for you, your template will look very
39 similar to ones used by Template Toolkit and "HTML::Mason" (the
40 Text::Template default delimiters are "{" and "}", but using
41 alternative delimiters speeds it up by about 25%, and the "<%" and "%>"
42 delimiters are 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
48 prepare
50 Returns a hash of all the fields ready to be rendered.
51 render
53 Uses the prepared hash and expands the template, returning a string of
54 HTML.
55
57 <% $jshead %> - JavaScript to stick in <head>
58 <% $title %> - The <title> of the HTML form
59 <% $start %> - Opening <form> tag and internal fields
60 <% $submit %> - The submit button(s)
61 <% $reset %> - The reset button
62 <% $end %> - Closing </form> tag
63 <% $fields %> - List of fields
64 <% $field %> - Hash of fields (for lookup by name)
65 Note that you refer to variables with a preceding "$", just like in
67 Perl. Like Template Toolkit, you can specify a variable to place
68 fields under:
69 my $form = CGI::FormBuilder->new(
71 fields => \@fields,
72 template => {
73 type => 'Text',
74 template => 'form.tmpl',
75 variable => 'form'
76 },
77 );
78 Unlike Template Toolkit, though, these will not be placed in OO-style,
80 dot-separated vars. Instead, a hash will be created which you then
81 reference:
82 <% $form{jshead} %>
84 <% $form{start} %>
85 etc.
86 And field data is in a hash-of-hashrefs format:
88 For a field named... The field data is in...
90 -------------------- -----------------------
91 job <% $form{field}{job} %]
92 size <% $form{field}{size} %]
93 email <% $form{field}{email} %]
94 Since "Text::Template" looks so much like Perl, you can access
96 individual elements and create variables like so:
97 <%
99 my $myfield = $form{field}{email};
100 $myfield->{label}; # text label
101 $myfield->{field}; # field input tag
102 $myfield->{value}; # first value
103 $myfield->{values}; # list of all values
104 $myfield->{options}; # list of all options
105 $myfield->{required}; # required flag
106 $myfield->{invalid}; # invalid flag
107 $myfield->{error}; # error string if invalid
108 %>
109 <%
111 for my $field (@{$form{fields}}) {
112 $OUT .= "<tr>\n<td>" . $field->{label} . "</td> <td>"
113 . $field->{field} . "</td>\n<tr>";
114 }
115 %>
116 In addition, when using the engine option, you supply an existing
118 Text::Template object or a hash of parameters to be passed to new().
119 For example, you can ask for different delimiters yourself:
120 my $form = CGI::FormBuilder->new(
122 fields => \@fields,
123 template => {
124 type => 'Text',
125 template => 'form.tmpl',
126 variable => 'form',
127 engine => {
128 DELIMITERS => [ '[@--', '--@]' ],
129 },
130 data => {
131 version => 1.23,
132 author => 'Fred Smith',
133 },
134 },
135 );
136 If you pass a hash of parameters, you can override the "TYPE" and
138 "SOURCE" parameters, as well as any other "Text::Template" options. For
139 example, you can pass in a string template with "TYPE => STRING"
140 instead of loading it from a file. You must specify both "TYPE" and
141 "SOURCE" if doing so. The good news is this is trivial:
142 my $form = CGI::FormBuilder->new(
144 fields => \@fields,
145 template => {
146 type => 'Text',
147 variable => 'form',
148 engine => {
149 TYPE => 'STRING',
150 SOURCE => $string,
151 DELIMITERS => [ '[@--', '--@]' ],
152 },
153 data => {
154 version => 1.23,
155 author => 'Fred Smith',
156 },
157 },
158 );
159 If you get the crazy idea to let users of your application pick the
161 template file (strongly discouraged) and you're getting errors, look at
162 the "Text::Template" documentation for the "UNTAINT" feature.
163 Also, note that "Text::Template"'s "PREPEND => 'use strict;'" option is
165 not recommended due to the dynamic nature for "FormBuilder". If you
166 use it, then you'll have to declare each variable that "FormBuilder"
167 puts into your template with "use vars qw($jshead' ... etc);"
168 If you're really stuck on this, though, a workaround is to say:
170 PREPEND => 'use strict; use vars qw(%form);'
172 and then set the option "variable => 'form'". That way you can have
174 strict Perl without too much hassle, except that your code might be
175 exhausting to look at :-). Things like
176 "$form{field}{your_field_name}{field}" end up being all over the place,
177 instead of the nicer short forms.
178 Finally, when you use the "data" template option, the keys you specify
180 will be available to the template as regular variables. In the above
181 example, these would be "<% $version %>" and "<% $author %>". And
182 complex datatypes are easy:
183 data => {
185 anArray => [ 1, 2, 3 ],
186 aHash => { orange => 'tangy', chocolate => 'sweet' },
187 }
188 This becomes the following in your template:
190 <%
192 @anArray; # you can use $myArray[1] etc.
193 %aHash; # you can use $myHash{chocolate} etc.
194 %>
195 For more information, please consult the "Text::Template"
197 documentation.
198
200 CGI::FormBuilder, CGI::FormBuilder::Template, Text::Template
201
203 $Id: Text.pm 100 2007-03-02 18:13:13Z nwiger $
204
206 Copyright (c) Nate Wiger <http://nateware.com>. All Rights Reserved.
207 Text::Template support is due to huge contributions by Jonathan
209 Buhacoff. Thanks man.
210 This module is free software; you may copy this under the terms of the
212 GNU General Public License, or the Artistic License, copies of which
213 should have accompanied your Perl kit.
214perl v5.36.0 2023-01-20CGI::FormBuilder::Template::Text(3)