1Template::FAQ(3)      User Contributed Perl Documentation     Template::FAQ(3)
2
3
4

NAME

6       Template::FAQ - Frequently Asked Questions about the Template Toolkit
7

DESCRIPTION

Template Toolkit Language

10       Why doesn't [% a = b IF c %] work as expected?
11
12       Because the parser interprets it as
13
14           [% a = (b IF c) %]
15
16       Do this instead:
17
18           [% SET a = b IF c %]
19
20       If I'm using TT to write out a TT template, is there a good way to
21       escape [% and %]?
22
23       You can do this:
24
25         [% stag = "[\%"
26            etag = "%\]"
27         %]
28
29       and then:
30
31         [% stag; 'hello'; etag %]
32
33       Or something like:
34
35         [% TAGS [- -] %]
36         [- INCLUDE foo -]   # is a directive
37         [% INCLUDE foo %]   # not a directive, just plain text, passed through
38
39       How do I iterate over a hash?
40
41       This is covered in the Template::Manual::VMethods section of the manual
42       page.  A list of all the keys that are in the hash can be obtained with
43       the 'keys' virtual method.  You can then iterate over that list and by
44       looking up each key in turn get the value.
45
46           [% FOREACH key = product.keys %]
47              [% key %] => [% product.$key %]
48           [% END %]
49

Plugins

51       How do I get the Table plugin to order data across rather than down?
52
53       Order the data into rows:
54
55            Steve     Karen     Jeff
56            Brooklyn  Nantucket Fairfax
57            NY        MA        VA
58
59           [% USE table(data, rows=3) %]
60
61       Then ask for each column
62
63           [% FOREACH column = table.cols %]
64
65       And then print each item in the column going across the output rows
66
67           [% FOREACH item = column %]
68               <td>[% item %]</td>
69           [% END %]
70
71       Accessing Cookies
72
73       Jeff Boes <jboes@nexcerpt.com> asks:
74
75           Does anyone have a quick-n-dirty approach to accessing
76           cookies from templates?
77
78       Jonas Liljegren answers:
79
80           [% USE CGI %]
81
82           <p>The value is [% CGI.cookie('cookie_name') ⎪ html %]
83

Extending the Template Toolkit

85       Can I serve templates from a database?
86
87       Short answer: yes, Chris Nandor has done this for Slash.  You need to
88       subclass Template::Provider.  See the mailing list archives for further
89       info.
90
91       Can I fetch templates via http?
92
93       To do the job properly, you should sublcass Template::Provider to Tem‐
94       plate::Provider::HTTP and use a PREFIX_MAP option to bind the 'http'
95       template prefix to that particular provider (you may want to go digging
96       around in the Changes file around version 2.01 for more info on PRE‐
97       FIX_MAP - it may not be properly documented anywhere else...yet!).
98       e.g. (untested due to lack of existing HTTP Provider - patches wel‐
99       come!).
100
101           use Template::Provider::HTTP;
102
103           my $file = Template::Provider( INCLUDE_PATH => [...] );
104           my $http = Template::Provider::HTTP->new(...);
105           my $tt2  = Template->new({
106               LOAD_TEMPLATES => [ $file, $http ],
107               PREFIX_MAP => {
108                   file    => '0',     # file:foo.html
109                   http    => '1',     # http:foo.html
110                   default => '0',     # foo.html => file:foo.html
111               }
112           });
113
114       Now a template specified as:
115
116           [% INCLUDE foo %]
117
118       will be served by the 'file' provider (the default).  Otherwise you can
119       explicitly add a prefix:
120
121           [% INCLUDE file:foo.html %]
122           [% INCLUDE http:foo.html %]
123           [% INCLUDE http://www.xyz.com/tt2/header.tt2 %]
124
125       This same principal can be used to create a DBI template provider.
126       e.g.
127
128           [% INCLUDE dbi:foo.html %]
129
130       But similarly, alas, we don't yet have a DBI provider as part of the
131       Template Toolkit.  There has been some talk on the mailing list about
132       efforts to develop DBI and/or HTTP providers but as yet no-one has
133       stepped forward to take up the challenge...
134
135       In the mean time, Craig's post from the mailing list has some useful
136       pointers on how to acheive this using existing modules:
137
138           To: Adam Theo <adamtheo@theoretic.com>
139           From: Craig Barratt <craig@arraycomm.com>
140           Date: Fri, 18 May 2001 17:06:59 -0700
141
142           > i was wondering if there is anyway to fetch a file using http:// or
143           > ftp:// and include that?
144
145           Here's one way.  Set the LOAD_PERL option:
146
147               use Template;
148
149               my $template = Template->new({
150                   LOAD_PERL => 1
151               });
152               $template->process("example.tt", { stdout => *STDOUT })
153                                            ⎪⎪ die $template->error();
154
155           and then use LWP::UserAgent and HTTP::Request:
156
157               [%
158                   USE ua = LWP.UserAgent;
159                   ua.proxy("http", "http://your_proxy/");
160                   USE req = HTTP.Request("GET", "http://www.cpan.org");
161                   ua.request(req).content;
162               -%]
163
164           For FTP use Net::FTP:
165
166               [%
167                   USE ftp = Net.FTP("ftp.cpan.org");
168                   x = ftp.login("anonymous", "me@here.there");
169                   x = ftp.cwd("/");
170                   x = ftp.get("welcome.msg", stdout);
171                   x = ftp.quit;
172               -%]
173
174           Normally ftp.get would write the file into the current directory.
175           Instead we pass stdout as a second argument so that it is written
176           to stdout.  We set stdout to STDOUT in the variables we pass to
177           process.
178
179           Craig
180

Miscellaneous

182       How can I find out the name of the main template being processed?
183
184       The "template" variable contains a reference to the Template::Document
185       object for the main template you're processing (i.e. the one provided
186       as the first argument to the Template process() method).  The "name"
187       method returns its name.
188
189           [% template.name %]     # e.g. index.html
190
191       How can I find out the name of the current template being processed?
192
193       The "template" variable always references the main template being pro‐
194       cessed.  So even if you call [% INCLUDE header %], and that calls [%
195       INCLUDE menu %], the "template" variable will be unchanged.
196
197       index.html:
198
199           [% template.name  %]     # index.html
200           [% INCLUDE header %]
201
202       header:
203
204           [% template.name  %]     # index.html
205           [% INCLUDE menu   %]
206
207       menu:
208
209           [% template.name  %]     # index.html
210
211       In constrast, the "component" variable always references the current
212       template being processed.
213
214       index.html
215
216           [% component.name %]     # index.html
217           [% INCLUDE header %]
218
219       header:
220
221           [% component.name %]     # header
222           [% INCLUDE menu   %]
223
224       menu:
225
226           [% component.name  %]     # menu
227
228       How do I print the modification time of the template or component?
229
230       The "template" and "component" variables reference the main template
231       and the current template being processed (see previous questions).  The
232       "modtime" method returns the modification time of the corresponding
233       template file as a number of seconds since the Unix epoch (00:00:00 GMT
234       1st January 1970).
235
236       This number doesn't mean much to anyone (except perhaps serious Unix
237       geeks) so you'll probably want to use the Date plugin to format it for
238       human consumption.
239
240           [% USE Date %]
241
242           [% template.name %] last modified [% Date.format(template.modtime) %]
243
244       How can I configure variables on a per-request basis?
245
246       One easy way to acheive this is to define a single PRE_PROCESS template
247       which loads in other configuration files based on variables defined or
248       other conditions.
249
250       For example, my setup usually looks something like this:
251
252           PRE_PROCESS => 'config/main'
253
254       config/main:
255
256           [%  DEFAULT  style   = 'text'
257                        section =  template.section or 'home';
258
259               PROCESS  config/site
260                     +  config/urls
261                     +  config/macros
262                     + "config/style/$style"
263                     + "config/section/$section"
264                     + ...
265           %]
266
267       This allows me to set a single 'style' variable to control which config
268       file gets pre-processed to set my various style options (colours, img
269       paths, etc).  For example:
270
271       config/style/basic:
272
273           [%  style = {
274                   name = style    # save existing 'style' var as 'style.name'
275
276                   # define various other style variables....
277                   col = {
278                       back => '#ffffff'
279                       text => '#000000'
280                           # ...etc...
281                   }
282
283                   logo = {
284                           # ...etc...
285                   }
286
287                   # ...etc...
288               }
289           %]
290
291       Each source template can declare which section it's in via a META
292       directive:
293
294         [% META
295              title   = 'General Information'
296              section = 'info'
297         %]
298
299         ...
300
301       This controls which section configuration file gets loaded to set vari‐
302       ous other variables for defining the section title, menu, etc.
303
304       config/section/info:
305
306           [%  section = {
307                       name   = section  # save 'section' var as 'section.name'
308                       title  = 'Information'
309                       menu   = [ ... ]
310                       # ...etc...
311                   }
312           %]
313
314       This illustrates the basic principal but you can extend it to perform
315       pretty much any kind of per-document initialisation that you require.
316

AUTHOR

318       Andy Wardley <abw@wardley.org>
319
320       <http://wardley.org/⎪http://wardley.org/>
321

VERSION

323       2.68, distributed as part of the Template Toolkit version 2.18,
324       released on 09 February 2007.
325

COPYRIGHT

327         Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
328
329       This module is free software; you can redistribute it and/or modify it
330       under the same terms as Perl itself.
331
332
333
334perl v5.8.8                       2007-02-09                  Template::FAQ(3)