.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "Template::FAQ 3" .TH Template::FAQ 3 2026-05-31 "perl v5.42.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Template::FAQ \- Frequently Asked Questions about the Template Toolkit .SH "Template Toolkit Language" .IX Header "Template Toolkit Language" .SS "Why doesn\*(Aqt [% a = b IF c %] work as expected?" .IX Subsection "Why doesn't [% a = b IF c %] work as expected?" There\*(Aqs a limitation in the TT2 parser which means that the following code doesn\*(Aqt work as you might expect: .PP .Vb 1 \& [% a = b IF c %] .Ve .PP The parser interprets it as an attempt to set \f(CW\*(C`a\*(C'\fR to the result of \&\f(CW\*(C`b IF c\*(C'\fR, like this: .PP .Vb 1 \& [% a = (b IF c) %] .Ve .PP If you want to set \f(CW\*(C`a = b\*(C'\fR only if \f(CW\*(C`c\*(C'\fR is true, then do this instead: .PP .Vb 1 \& [% SET a = b IF c %] .Ve .PP The explicit \f(CW\*(C`SET\*(C'\fR keyword gives the parser the clue it needs to do the right thing. .SS "If I\*(Aqm using TT to write out a TT template, is there a good way to escape [% and %]?" .IX Subsection "If I'm using TT to write out a TT template, is there a good way to escape [% and %]?" You can do something like this: .PP .Vb 3 \& [% stag = "[\e%" \& etag = "%\e]" \& %] .Ve .PP and then: .PP .Vb 1 \& [% stag; \*(Aqhello\*(Aq; etag %] .Ve .PP Or you can use the \f(CW\*(C`TAGS\*(C'\fR directive, like so: .PP .Vb 3 \& [% TAGS [\- \-] %] \& [\- INCLUDE foo \-] # is a directive \& [% INCLUDE foo %] # not a directive .Ve .SS "How do I iterate over a hash?" .IX Subsection "How do I iterate over a hash?" This is covered in the Template::Manual::VMethods section of the manual. A list of all the keys that are in the hash can be obtained with the \&\f(CW\*(C`keys\*(C'\fR virtual method. You can then iterate over that list and by looking up each key in turn get the value. .PP .Vb 3 \& [% FOREACH key = product.keys %] \& [% key %] => [% product.$key %] \& [% END %] .Ve .SH Plugins .IX Header "Plugins" .SS "How do I get the Table plugin to order data across rather than down?" .IX Subsection "How do I get the Table plugin to order data across rather than down?" Order the data into rows: .PP .Vb 3 \& Steve Karen Jeff \& Brooklyn Nantucket Fairfax \& NY MA VA \& \& [% USE table(data, rows=3) %] .Ve .PP Then ask for each column .PP .Vb 1 \& [% FOREACH column = table.cols %] .Ve .PP And then print each item in the column going across the output rows .PP .Vb 3 \& [% FOREACH item = column %] \& [% item %] \& [% END %] .Ve .SS "Accessing Cookies" .IX Subsection "Accessing Cookies" Jeff Boes asks: .PP .Vb 2 \& Does anyone have a quick\-n\-dirty approach to accessing \& cookies from templates? .Ve .PP Jonas Liljegren answers: .PP .Vb 1 \& [% USE CGI %] \& \&

The value is [% CGI.cookie(\*(Aqcookie_name\*(Aq) | html %] .Ve .PP You will need to have Template::Plugin::CGI installed. .SH "Extending the Template Toolkit" .IX Header "Extending the Template Toolkit" .SS "Can I serve templates from a database?" .IX Subsection "Can I serve templates from a database?" Short answer: yes, Chris Nandor has done this for Slash. You need to subclass Template::Provider. See the mailing list archives for further info. .SS "Can I fetch templates via http?" .IX Subsection "Can I fetch templates via http?" To do the job properly, you should subclass Template::Provider to \&\f(CW\*(C`Template::Provider::HTTP\*(C'\fR and use a \f(CW\*(C`PREFIX_MAP\*(C'\fR option to bind the \f(CW\*(C`http\*(C'\fR template prefix to that particular provider (you may want to go digging around in the \fIChanges\fR file around version 2.01 for more info on \f(CW\*(C`PREFIX_MAP\*(C'\fR \- it may not be properly documented anywhere else...yet!). e.g. .PP .Vb 1 \& use Template::Provider::HTTP; \& \& my $file = Template::Provider( INCLUDE_PATH => [...] ); \& my $http = Template::Provider::HTTP\->new(...); \& my $tt2 = Template\->new({ \& LOAD_TEMPLATES => [ $file, $http ], \& PREFIX_MAP => { \& file => \*(Aq0\*(Aq, # file:foo.html \& http => \*(Aq1\*(Aq, # http:foo.html \& default => \*(Aq0\*(Aq, # foo.html => file:foo.html \& } \& }); .Ve .PP Now a template specified as: .PP .Vb 1 \& [% INCLUDE foo %] .Ve .PP will be served by the \*(Aqfile\*(Aq provider (the default). Otherwise you can explicitly add a prefix: .PP .Vb 3 \& [% INCLUDE file:foo.html %] \& [% INCLUDE http:foo.html %] \& [% INCLUDE http://www.xyz.com/tt2/header.tt2 %] .Ve .PP This same principal can be used to create a DBI template provider. e.g. .PP .Vb 1 \& [% INCLUDE dbi:foo.html %] .Ve .PP Alas, we don\*(Aqt yet have a DBI provider as part of the Template Toolkit. There has been some talk on the mailing list about efforts to develop DBI and/or HTTP providers but as yet no\-one has stepped forward to take up the challenge... .PP In the mean time, Craig Barrat\*(Aqs post from the mailing list has some useful pointers on how to achieve this using existing modules. See .SH Miscellaneous .IX Header "Miscellaneous" .SS "How can I find out the name of the main template being processed?" .IX Subsection "How can I find out the name of the main template being processed?" The \f(CW\*(C`template\*(C'\fR variable contains a reference to the Template::Document object for the main template you\*(Aqre processing (i.e. the one provided as the first argument to the Template \fBprocess()\fR method). The \f(CW\*(C`name\*(C'\fR method returns its name. .PP .Vb 1 \& [% template.name %] # e.g. index.html .Ve .SS "How can I find out the name of the current template being processed?" .IX Subsection "How can I find out the name of the current template being processed?" The \f(CW\*(C`template\*(C'\fR variable always references the \fImain\fR template being processed. So even if you call [% INCLUDE header %], and that calls [% INCLUDE menu %], the \f(CW\*(C`template\*(C'\fR variable will be unchanged. .PP index.html: .PP .Vb 2 \& [% template.name %] # index.html \& [% INCLUDE header %] .Ve .PP header: .PP .Vb 2 \& [% template.name %] # index.html \& [% INCLUDE menu %] .Ve .PP menu: .PP .Vb 1 \& [% template.name %] # index.html .Ve .PP In contrast, the \f(CW\*(C`component\*(C'\fR variable always references the \fIcurrent\fR template being processed. .PP index.html .PP .Vb 2 \& [% component.name %] # index.html \& [% INCLUDE header %] .Ve .PP header: .PP .Vb 2 \& [% component.name %] # header \& [% INCLUDE menu %] .Ve .PP menu: .PP .Vb 1 \& [% component.name %] # menu .Ve .SS "How do I print the modification time of the template or component?" .IX Subsection "How do I print the modification time of the template or component?" The \f(CW\*(C`template\*(C'\fR and \f(CW\*(C`component\*(C'\fR variables reference the main template and the current template being processed (see previous questions). The \f(CW\*(C`modtime\*(C'\fR method returns the modification time of the corresponding template file as a number of seconds since the Unix epoch (00:00:00 GMT 1st January 1970). .PP This number doesn\*(Aqt mean much to anyone (except perhaps serious Unix geeks) so you\*(Aqll probably want to use the Date plugin to format it for human consumption. .PP .Vb 2 \& [% USE Date %] \& [% template.name %] last modified [% Date.format(template.modtime) %] .Ve .SS "How can I configure variables on a per\-request basis?" .IX Subsection "How can I configure variables on a per-request basis?" One easy way to achieve this is to define a single \f(CW\*(C`PRE_PROCESS\*(C'\fR template which loads in other configuration files based on variables defined or other conditions. .PP For example, my setup usually looks something like this: .PP .Vb 1 \& PRE_PROCESS => \*(Aqconfig/main\*(Aq .Ve .PP config/main: .PP .Vb 2 \& [% DEFAULT style = \*(Aqtext\*(Aq \& section = template.section or \*(Aqhome\*(Aq; \& \& PROCESS config/site \& + config/urls \& + config/macros \& + "config/style/$style" \& + "config/section/$section" \& + ... \& %] .Ve .PP This allows me to set a single \*(Aqstyle\*(Aq variable to control which config file gets pre\-processed to set my various style options (colours, img paths, etc). For example: .PP config/style/basic: .PP .Vb 2 \& [% style = { \& name = style # save existing \*(Aqstyle\*(Aq var as \*(Aqstyle.name\*(Aq \& \& # define various other style variables.... \& col = { \& back => \*(Aq#ffffff\*(Aq \& text => \*(Aq#000000\*(Aq \& # ...etc... \& } \& \& logo = { \& # ...etc... \& } \& \& # ...etc... \& } \& %] .Ve .PP Each source template can declare which section it\*(Aqs in via a META directive: .PP .Vb 5 \& [% META \& title = \*(AqGeneral Information\*(Aq \& section = \*(Aqinfo\*(Aq \& %] \& ... .Ve .PP This controls which section configuration file gets loaded to set various other variables for defining the section title, menu, etc. .PP config/section/info: .PP .Vb 7 \& [% section = { \& name = section # save \*(Aqsection\*(Aq var as \*(Aqsection.name\*(Aq \& title = \*(AqInformation\*(Aq \& menu = [ ... ] \& # ...etc... \& } \& %] .Ve .PP This illustrates the basic principal but you can extend it to perform pretty much any kind of per\-document initialisation that you require. .SS "Why do I get rubbish for my utf\-8 templates?" .IX Subsection "Why do I get rubbish for my utf-8 templates?" First of all, make sure that your template files define a Byte Order Mark .PP If you for some reason don\*(Aqt want to add BOM to your templates, you can force Template to use a particular encoding (e.g. \f(CW\*(C`utf8\*(C'\fR) for your templates with the \f(CW\*(C`ENCODING\*(C'\fR option. .PP .Vb 3 \& my $template = Template\->new({ \& ENCODING => \*(Aqutf8\*(Aq \& }); .Ve .SH "Questions About This FAQ" .IX Header "Questions About This FAQ" .SS "Why is this FAQ so short?" .IX Subsection "Why is this FAQ so short?" Because we don\*(Aqt have anyone maintaining it. .SS "Can I help?" .IX Subsection "Can I help?" Yes please :\-)