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

NAME

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

SYNOPSIS

10           my $form = CGI::FormBuilder->new(
11                           fields   => \@fields,
12                           template => {
13                               type => 'Text',
14                               template => 'form.tmpl',
15                               variable => 'form',
16                           }
17                      );
18

DESCRIPTION

20       This engine adapts FormBuilder to use "Text::Template". Usage is very
21       similar to Template Toolkit:
22
23           my $form = CGI::FormBuilder->new(
24                           fields => \@fields,
25                           template => {
26                               type => 'Text',           # use Text::Template
27                               template => 'form.tmpl',
28                           }
29                      );
30
31       The default options passed into "Text::Template->new()" with this
32       calling form are:
33
34           TYPE   => 'FILE'
35           SOURCE => 'form.tmpl'
36           DELIMITERS => ['<%','%>']
37
38       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
44       The following methods are provided (usually only used internally):
45
46   engine
47       Returns a reference to the "Text::Template" object
48
49   prepare
50       Returns a hash of all the fields ready to be rendered.
51
52   render
53       Uses the prepared hash and expands the template, returning a string of
54       HTML.
55

TEMPLATES

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
66       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
70           my $form = CGI::FormBuilder->new(
71               fields => \@fields,
72               template => {
73                    type => 'Text',
74                    template => 'form.tmpl',
75                    variable => 'form'
76               },
77           );
78
79       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
83           <% $form{jshead} %>
84           <% $form{start}  %>
85           etc.
86
87       And field data is in a hash-of-hashrefs format:
88
89           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
95       Since "Text::Template" looks so much like Perl, you can access
96       individual elements and create variables like so:
97
98           <%
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
110           <%
111               for my $field (@{$form{fields}}) {
112                   $OUT .= "<tr>\n<td>" . $field->{label} . "</td> <td>"
113                                        . $field->{field} . "</td>\n<tr>";
114               }
115           %>
116
117       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
121           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
137       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
143           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
160       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
164       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
169       If you're really stuck on this, though, a workaround is to say:
170
171           PREPEND => 'use strict; use vars qw(%form);'
172
173       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
179       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
184           data => {
185                   anArray => [ 1, 2, 3 ],
186                   aHash => { orange => 'tangy', chocolate => 'sweet' },
187           }
188
189       This becomes the following in your template:
190
191           <%
192               @anArray;    # you can use $myArray[1] etc.
193               %aHash;      # you can use $myHash{chocolate} etc.
194           %>
195
196       For more information, please consult the "Text::Template"
197       documentation.
198

SEE ALSO

200       CGI::FormBuilder, CGI::FormBuilder::Template, Text::Template
201

REVISION

203       $Id: Text.pm 100 2007-03-02 18:13:13Z nwiger $
204

AUTHOR

206       Copyright (c) Nate Wiger <http://nateware.com>. All Rights Reserved.
207
208       Text::Template support is due to huge contributions by Jonathan
209       Buhacoff.  Thanks man.
210
211       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.
214
215
216
217perl v5.36.0                      2023-01-20CGI::FormBuilder::Template::Text(3)
Impressum