1#============================================================= -*-perl-*- 2# 3# Template::FAQ 4# 5# DESCRIPTION 6 7# 8# AUTHOR 9# Andy Wardley <abw@wardley.org> 10# 11# COPYRIGHT 12# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. 13# 14# This module is free software; you can redistribute it and/or 15# modify it under the same terms as Perl itself. 16#======================================================================== 17 18=head1 NAME 19 20Template::FAQ - Frequently Asked Questions about the Template Toolkit 21 22=head1 Template Toolkit Language 23 24=head2 Why doesn't [% a = b IF c %] work as expected? 25 26There's a limitation in the TT2 parser which means that the following code 27doesn't work as you might expect: 28 29 [% a = b IF c %] 30 31The parser interprets it as an attempt to set C<a> to the result of 32C<b IF c>, like this: 33 34 [% a = (b IF c) %] 35 36If you want to set C<a = b> only if C<c> is true, then do this instead: 37 38 [% SET a = b IF c %] 39 40The explicit C<SET> keyword gives the parser the clue it needs to do the 41right thing. 42 43NOTE: this will be fixed in TT3 44 45=head2 If I'm using TT to write out a TT template, is there a good way to escape [% and %]? 46 47You can do something like this: 48 49 [% stag = "[\%" 50 etag = "%\]" 51 %] 52 53and then: 54 55 [% stag; 'hello'; etag %] 56 57Or you can use the C<TAGS> directive, like so: 58 59 [% TAGS [- -] %] 60 [- INCLUDE foo -] # is a directive 61 [% INCLUDE foo %] # not a directive 62 63=head2 How do I iterate over a hash? 64 65This is covered in the L<Template::Manual::VMethods> section of the 66manual. A list of all the keys that are in the hash can be obtained with the 67C<keys> virtual method. You can then iterate over that list and by looking up 68each key in turn get the value. 69 70 [% FOREACH key = product.keys %] 71 [% key %] => [% product.$key %] 72 [% END %] 73 74=head1 Plugins 75 76=head2 How do I get the Table plugin to order data across rather than down? 77 78Order the data into rows: 79 80 Steve Karen Jeff 81 Brooklyn Nantucket Fairfax 82 NY MA VA 83 84 [% USE table(data, rows=3) %] 85 86Then ask for each column 87 88 [% FOREACH column = table.cols %] 89 90And then print each item in the column going across the output rows 91 92 [% FOREACH item = column %] 93 <td>[% item %]</td> 94 [% END %] 95 96=head2 Accessing Cookies 97 98Jeff Boes E<lt>jboes@nexcerpt.comE<gt> asks: 99 100 Does anyone have a quick-n-dirty approach to accessing 101 cookies from templates? 102 103Jonas Liljegren answers: 104 105 [% USE CGI %] 106 107 <p>The value is [% CGI.cookie('cookie_name') | html %] 108 109 110=head1 Extending the Template Toolkit 111 112=head2 Can I serve templates from a database? 113 114Short answer: yes, Chris Nandor has done this for Slash. You need to 115subclass L<Template::Provider>. See the mailing list archives for further 116info. 117 118=head2 Can I fetch templates via http? 119 120To do the job properly, you should subclass L<Template::Provider> to 121C<Template::Provider::HTTP> and use a C<PREFIX_MAP> option to bind the C<http> 122template prefix to that particular provider (you may want to go digging around 123in the F<Changes> file around version 2.01 for more info on C<PREFIX_MAP> - it 124may not be properly documented anywhere else...yet!). e.g. 125 126 use Template::Provider::HTTP; 127 128 my $file = Template::Provider( INCLUDE_PATH => [...] ); 129 my $http = Template::Provider::HTTP->new(...); 130 my $tt2 = Template->new({ 131 LOAD_TEMPLATES => [ $file, $http ], 132 PREFIX_MAP => { 133 file => '0', # file:foo.html 134 http => '1', # http:foo.html 135 default => '0', # foo.html => file:foo.html 136 } 137 }); 138 139Now a template specified as: 140 141 [% INCLUDE foo %] 142 143will be served by the 'file' provider (the default). Otherwise you 144can explicitly add a prefix: 145 146 [% INCLUDE file:foo.html %] 147 [% INCLUDE http:foo.html %] 148 [% INCLUDE http://www.xyz.com/tt2/header.tt2 %] 149 150This same principal can be used to create a DBI template provider. e.g. 151 152 [% INCLUDE dbi:foo.html %] 153 154Alas, we don't yet have a DBI provider as part of the Template Toolkit. There 155has been some talk on the mailing list about efforts to develop DBI and/or 156HTTP providers but as yet no-one has stepped forward to take up the 157challenge... 158 159In the mean time, Craig Barrat's post from the mailing list has some useful 160pointers on how to achieve this using existing modules. See 161L<http://tt2.org/pipermail/templates/2001-May/000954.html> 162 163=head1 Miscellaneous 164 165=head2 How can I find out the name of the main template being processed? 166 167The C<template> variable contains a reference to the 168Template::Document object for the main template you're processing 169(i.e. the one provided as the first argument to the Template process() 170method). The C<name> method returns its name. 171 172 [% template.name %] # e.g. index.html 173 174=head2 How can I find out the name of the current template being processed? 175 176The C<template> variable always references the I<main> template being processed. 177So even if you call [% INCLUDE header %], and that calls [% INCLUDE menu %], 178the C<template> variable will be unchanged. 179 180index.html: 181 182 [% template.name %] # index.html 183 [% INCLUDE header %] 184 185header: 186 187 [% template.name %] # index.html 188 [% INCLUDE menu %] 189 190menu: 191 192 [% template.name %] # index.html 193 194In constrast, the C<component> variable always references the I<current> 195template being processed. 196 197index.html 198 199 [% component.name %] # index.html 200 [% INCLUDE header %] 201 202header: 203 204 [% component.name %] # header 205 [% INCLUDE menu %] 206 207menu: 208 209 [% component.name %] # menu 210 211=head2 How do I print the modification time of the template or component? 212 213The C<template> and C<component> variables reference the main template 214and the current template being processed (see previous questions). 215The C<modtime> method returns the modification time of the 216corresponding template file as a number of seconds since the Unix 217epoch (00:00:00 GMT 1st January 1970). 218 219This number doesn't mean much to anyone (except perhaps serious Unix 220geeks) so you'll probably want to use the Date plugin to format it for 221human consumption. 222 223 [% USE Date %] 224 [% template.name %] last modified [% Date.format(template.modtime) %] 225 226=head2 How can I configure variables on a per-request basis? 227 228One easy way to achieve this is to define a single C<PRE_PROCESS> template 229which loads in other configuration files based on variables defined or other 230conditions. 231 232For example, my setup usually looks something like this: 233 234 PRE_PROCESS => 'config/main' 235 236config/main: 237 238 [% DEFAULT style = 'text' 239 section = template.section or 'home'; 240 241 PROCESS config/site 242 + config/urls 243 + config/macros 244 + "config/style/$style" 245 + "config/section/$section" 246 + ... 247 %] 248 249This allows me to set a single 'style' variable to control which config 250file gets pre-processed to set my various style options (colours, img paths, 251etc). For example: 252 253config/style/basic: 254 255 [% style = { 256 name = style # save existing 'style' var as 'style.name' 257 258 # define various other style variables.... 259 col = { 260 back => '#ffffff' 261 text => '#000000' 262 # ...etc... 263 } 264 265 logo = { 266 # ...etc... 267 } 268 269 # ...etc... 270 } 271 %] 272 273Each source template can declare which section it's in via a META 274directive: 275 276 [% META 277 title = 'General Information' 278 section = 'info' 279 %] 280 ... 281 282This controls which section configuration file gets loaded to set various 283other variables for defining the section title, menu, etc. 284 285config/section/info: 286 287 [% section = { 288 name = section # save 'section' var as 'section.name' 289 title = 'Information' 290 menu = [ ... ] 291 # ...etc... 292 } 293 %] 294 295This illustrates the basic principal but you can extend it to perform 296pretty much any kind of per-document initialisation that you require. 297 298=head2 Why do I get rubbish for my utf-8 templates? 299 300First of all, make sure that your template files define a Byte Order 301Mark L<http://en.wikipedia.org/wiki/Byte_Order_Mark> 302 303If you for some reason don't want to add BOM to your templates, you can 304force Template to use a particular encoding (e.g. C<utf8>) for your 305templates with the C<ENCODING> option. 306 307 my $template = Template->new({ 308 ENCODING => 'utf8' 309 }); 310 311=head1 Questions About This FAQ 312 313=head2 Why is this FAQ so short? 314 315Because we don't have anyone maintaining it. 316 317=head2 Can I help? 318 319Yes please :-) 320 321=cut 322 323# Local Variables: 324# mode: perl 325# perl-indent-level: 4 326# indent-tabs-mode: nil 327# End: 328# 329# vim: expandtab shiftwidth=4: 330