[%#
# IMPORTANT NOTE
# This documentation is generated automatically from source
# templates. Any changes you make here may be lost.
#
# The 'docsrc' documentation source bundle is available for download
# from http://www.template-toolkit.org/docs.html and contains all
# the source templates, XML files, scripts, etc., from which the
# documentation for the Template Toolkit is built.
-%]
[% META book = 'Manual'
page = 'Config'
%]
[% WRAPPER toc;
PROCESS tocitem
title ="DESCRIPTION"
subs = [
"Template Style and Parsing Options",
"Template Files and Blocks",
"Template Variables",
"Runtime Processing Options",
"Caching and Compiling Options",
"Plugins and Filters",
"Compatibility, Customisation and Extension"
];
PROCESS tocitem
title ="AUTHOR"
subs = [];
PROCESS tocitem
title ="VERSION"
subs = [];
PROCESS tocitem
title ="COPYRIGHT"
subs = [];
END
%]
<!-- Pod to HTML conversion by the Template Toolkit version 2 -->
[% WRAPPER section
title="DESCRIPTION"
-%]<p>
This section contains details of all the configuration options that can
be used to customise the behaviour and extend the features of the
Template Toolkit.
</p>
[% WRAPPER subsection
title = "Template Style and Parsing Options"
-%]<ul>
<li><b>START_TAG, END_TAG</b><br>
<p>
The START_TAG and END_TAG options are used to specify character
sequences or regular expressions that mark the start and end of a
template directive. The default values for START_TAG and END_TAG are
'[% tt_start_tag %]' and '[% tt_end_tag %]' respectively, giving us the familiar directive style:
</p>
<pre> [% tt_start_tag %] example [% tt_end_tag %]</pre>
<p>
Any Perl regex characters can be used and therefore should be escaped
(or use the Perl <code>'quotemeta'</code> function) if they are intended to
represent literal characters.
</p>
<pre> my $template = Template->new({
START_TAG => quotemeta('<+'),
END_TAG => quotemeta('+>'),
});</pre>
<p>
example:
</p>
<pre> <+ INCLUDE foobar +></pre>
<p>
The TAGS directive can also be used to set the START_TAG and END_TAG values
on a per-template file basis.
</p>
<pre> [% tt_start_tag %] TAGS <+ +> [% tt_end_tag %]</pre>
<li><b>TAG_STYLE</b><br>
<p>
The TAG_STYLE option can be used to set both START_TAG and END_TAG
according to pre-defined tag styles.
</p>
<pre> my $template = Template->new({
TAG_STYLE => 'star',
});</pre>
<p>
Available styles are:
</p>
<pre> template [% tt_start_tag %] ... [% tt_end_tag %] (default)
template1 [% tt_start_tag %] ... [% tt_end_tag %] or %% ... %% (TT version 1)
metatext %% ... %% (Text::MetaText)
star [* ... *] (TT alternate)
php <? ... ?> (PHP)
asp <% ... %> (ASP)
mason <% ... > (HTML::Mason)
html <!-- ... --> (HTML comments)</pre>
<p>
Any values specified for START_TAG and/or END_TAG will over-ride
those defined by a TAG_STYLE.
</p>
<p>
The TAGS directive may also be used to set a TAG_STYLE
</p>
<pre> [% tt_start_tag %] TAGS html [% tt_end_tag %]
<!-- INCLUDE header --></pre>
<li><b>PRE_CHOMP, POST_CHOMP</b><br>
<p>
Anything outside a directive tag is considered plain text and is
generally passed through unaltered (but see the INTERPOLATE option).
This includes all whitespace and newlines characters surrounding
directive tags. Directives that don't generate any output will leave
gaps in the output document.
</p>
<p>
Example:
</p>
<pre> Foo
[% tt_start_tag %] a = 10 [% tt_end_tag %]
Bar</pre>
<p>
Output:
</p>
<pre> Foo</pre>
<pre> Bar</pre>
<p>
The PRE_CHOMP and POST_CHOMP options can help to clean up some of this
extraneous whitespace. Both are disabled by default.
</p>
<pre> my $template = Template->new({
PRE_CHOMP => 1,
POST_CHOMP => 1,
});</pre>
<p>
With PRE_CHOMP set to 1, the newline and whitespace preceding a directive
at the start of a line will be deleted. This has the effect of
concatenating a line that starts with a directive onto the end of the
previous line.
</p>
<pre> Foo <----------.
|
,---(PRE_CHOMP)----'
|
`-- [% tt_start_tag %] a = 10 [% tt_end_tag %] --.
|
,---(POST_CHOMP)---'
|
`-> Bar</pre>
<p>
With POST_CHOMP set to 1, any whitespace after a directive up to and
including the newline will be deleted. This has the effect of joining
a line that ends with a directive onto the start of the next line.
</p>
<p>
If PRE_CHOMP or POST_CHOMP is set to 2, then instead of removing all
the whitespace, the whitespace will be collapsed to a single space.
This is useful for HTML, where (usually) a contiguous block of
whitespace is rendered the same as a single space.
</p>
<p>
You may use the CHOMP_NONE, CHOMP_ALL, and CHOMP_COLLAPSE constants
from the Template::Constants module to deactivate chomping, remove
all whitespace, or collapse whitespace to a single space.
</p>
<p>
PRE_CHOMP and POST_CHOMP can be activated for individual directives by
placing a '-' immediately at the start and/or end of the directive.
</p>
<pre> [% tt_start_tag %] FOREACH user = userlist [% tt_end_tag %]
[% tt_start_tag %]- user -[% tt_end_tag %]
[% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
The '-' characters activate both PRE_CHOMP and POST_CHOMP for the one
directive '[% tt_start_tag %]- name -[% tt_end_tag %]'. Thus, the template will be processed as if
written:
</p>
<pre> [% tt_start_tag %] FOREACH user = userlist [% tt_end_tag %][% tt_start_tag %] user [% tt_end_tag %][% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
Note that this is the same as if PRE_CHOMP and POST_CHOMP were set
to CHOMP_ALL; the only way to get the CHOMP_COLLAPSE behavior is
to set PRE_CHOMP or POST_CHOMP accordingly. If PRE_CHOMP or POST_CHOMP
is already set to CHOMP_COLLAPSE, using '-' will give you CHOMP_COLLAPSE
behavior, not CHOMP_ALL behavior.
</p>
<p>
Similarly, '+' characters can be used to disable PRE_CHOMP or
POST_CHOMP (i.e. leave the whitespace/newline intact) options on a
per-directive basis.
</p>
<pre> [% tt_start_tag %] FOREACH user = userlist [% tt_end_tag %]
User: [% tt_start_tag %] user +[% tt_end_tag %]
[% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
With POST_CHOMP enabled, the above example would be parsed as if written:
</p>
<pre> [% tt_start_tag %] FOREACH user = userlist [% tt_end_tag %]User: [% tt_start_tag %] user [% tt_end_tag %]
[% tt_start_tag %] END [% tt_end_tag %]</pre>
<li><b>TRIM</b><br>
<p>
The TRIM option can be set to have any leading and trailing whitespace
automatically removed from the output of all template files and BLOCKs.
</p>
<p>
By example, the following BLOCK definition
</p>
<pre> [% tt_start_tag %] BLOCK foo [% tt_end_tag %]
Line 1 of foo
[% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
will be processed is as "\nLine 1 of foo\n". When INCLUDEd, the surrounding
newlines will also be introduced.
</p>
<pre> before
[% tt_start_tag %] INCLUDE foo [% tt_end_tag %]
after</pre>
<p>
output:
before
</p>
<pre> Line 1 of foo</pre>
<pre> after</pre>
<p>
With the TRIM option set to any true value, the leading and trailing
newlines (which count as whitespace) will be removed from the output
of the BLOCK.
</p>
<pre> before
Line 1 of foo
after</pre>
<p>
The TRIM option is disabled (0) by default.
</p>
<li><b>INTERPOLATE</b><br>
<p>
The INTERPOLATE flag, when set to any true value will cause variable
references in plain text (i.e. not surrounded by START_TAG and END_TAG)
to be recognised and interpolated accordingly.
</p>
<pre> my $template = Template->new({
INTERPOLATE => 1,
});</pre>
<p>
Variables should be prefixed by a '$' to identify them. Curly braces
can be used in the familiar Perl/shell style to explicitly scope the
variable name where required.
</p>
<pre> # INTERPOLATE => 0
<a href="http://[% tt_start_tag %] server [% tt_end_tag %]/[% tt_start_tag %] help [% tt_end_tag %]">
<img src="[% tt_start_tag %] images [% tt_end_tag %]/help.gif"></a>
[% tt_start_tag %] myorg.name [% tt_end_tag %]
# INTERPOLATE => 1
<a href="http://$server/$help">
<img src="$images/help.gif"></a>
$myorg.name
# explicit scoping with { }
<img src="$images/${icon.next}.gif"></pre>
<p>
Note that a limitation in Perl's regex engine restricts the maximum length
of an interpolated template to around 32 kilobytes or possibly less. Files
that exceed this limit in size will typically cause Perl to dump core with
a segmentation fault. If you routinely process templates of this size
then you should disable INTERPOLATE or split the templates in several
smaller files or blocks which can then be joined backed together via
PROCESS or INCLUDE.
</p>
<li><b>ANYCASE</b><br>
<p>
By default, directive keywords should be expressed in UPPER CASE. The
ANYCASE option can be set to allow directive keywords to be specified
in any case.
</p>
<pre> # ANYCASE => 0 (default)
[% tt_start_tag %] INCLUDE foobar [% tt_end_tag %] # OK
[% tt_start_tag %] include foobar [% tt_end_tag %] # ERROR
[% tt_start_tag %] include = 10 [% tt_end_tag %] # OK, 'include' is a variable</pre>
<pre> # ANYCASE => 1
[% tt_start_tag %] INCLUDE foobar [% tt_end_tag %] # OK
[% tt_start_tag %] include foobar [% tt_end_tag %] # OK
[% tt_start_tag %] include = 10 [% tt_end_tag %] # ERROR, 'include' is reserved word</pre>
<p>
One side-effect of enabling ANYCASE is that you cannot use a variable
of the same name as a reserved word, regardless of case. The reserved
words are currently:
</p>
<pre> GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER
IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE
USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META
TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP
CLEAR TO STEP AND OR NOT MOD DIV END</pre>
<p>
The only lower case reserved words that cannot be used for variables,
regardless of the ANYCASE option, are the operators:
</p>
<pre> and or not mod div</pre>
</ul>
[%- END %]
[% WRAPPER subsection
title = "Template Files and Blocks"
-%]<ul>
<li><b>INCLUDE_PATH</b><br>
<p>
The INCLUDE_PATH is used to specify one or more directories in which
template files are located. When a template is requested that isn't
defined locally as a BLOCK, each of the INCLUDE_PATH directories is
searched in turn to locate the template file. Multiple directories
can be specified as a reference to a list or as a single string where
each directory is delimited by ':'.
</p>
<pre> my $template = Template->new({
INCLUDE_PATH => '/usr/local/templates',
});
my $template = Template->new({
INCLUDE_PATH => '/usr/local/templates:/tmp/my/templates',
});
my $template = Template->new({
INCLUDE_PATH => [ '/usr/local/templates',
'/tmp/my/templates' ],
});</pre>
<p>
On Win32 systems, a little extra magic is invoked, ignoring delimiters
that have ':' followed by a '/' or '\'. This avoids confusion when using
directory names like 'C:\Blah Blah'.
</p>
<p>
When specified as a list, the INCLUDE_PATH path can contain elements
which dynamically generate a list of INCLUDE_PATH directories. These
generator elements can be specified as a reference to a subroutine or
an object which implements a paths() method.
</p>
<pre> my $template = Template->new({
INCLUDE_PATH => [ '/usr/local/templates',
\&incpath_generator,
My::IncPath::Generator->new( ... ) ],
});</pre>
<p>
Each time a template is requested and the INCLUDE_PATH examined, the
subroutine or object method will be called. A reference to a list of
directories should be returned. Generator subroutines should report
errors using die(). Generator objects should return undef and make an
error available via its error() method.
</p>
<p>
For example:
</p>
<pre> sub incpath_generator {</pre>
<pre> # ...some code...
if ($all_is_well) {
return \@list_of_directories;
}
else {
die "cannot generate INCLUDE_PATH...\n";
}
}</pre>
<p>
or:
</p>
<pre> package My::IncPath::Generator;</pre>
<pre> # Template::Base (or Class::Base) provides error() method
use Template::Base;
use base qw( Template::Base );</pre>
<pre> sub paths {
my $self = shift;</pre>
<pre> # ...some code...</pre>
<pre> if ($all_is_well) {
return \@list_of_directories;
}
else {
return $self->error("cannot generate INCLUDE_PATH...\n");
}
}</pre>
<pre> 1;</pre>
<li><b>DELIMITER</b><br>
<p>
Used to provide an alternative delimiter character sequence for
separating paths specified in the INCLUDE_PATH. The default
value for DELIMITER is ':'.
</p>
<pre> # tolerate Silly Billy's file system conventions
my $template = Template->new({
DELIMITER => '; ',
INCLUDE_PATH => 'C:/HERE/NOW; D:/THERE/THEN',
});</pre>
<pre> # better solution: install Linux! :-)</pre>
<p>
On Win32 systems, the default delimiter is a little more intelligent,
splitting paths only on ':' characters that aren't followed by a '/'.
This means that the following should work as planned, splitting the
INCLUDE_PATH into 2 separate directories, C:/foo and C:/bar.
</p>
<pre> # on Win32 only
my $template = Template->new({
INCLUDE_PATH => 'C:/Foo:C:/Bar'
});</pre>
<p>
However, if you're using Win32 then it's recommended that you
explicitly set the DELIMITER character to something else (e.g. ';')
rather than rely on this subtle magic.
</p>
<li><b>ABSOLUTE</b><br>
<p>
The ABSOLUTE flag is used to indicate if templates specified with
absolute filenames (e.g. '/foo/bar') should be processed. It is
disabled by default and any attempt to load a template by such a
name will cause a 'file' exception to be raised.
</p>
<pre> my $template = Template->new({
ABSOLUTE => 1,
});</pre>
<pre> # this is why it's disabled by default
[% tt_start_tag %] INSERT /etc/passwd [% tt_end_tag %]</pre>
<p>
On Win32 systems, the regular expression for matching absolute
pathnames is tweaked slightly to also detect filenames that start
with a driver letter and colon, such as:
</p>
<pre> C:/Foo/Bar</pre>
<li><b>RELATIVE</b><br>
<p>
The RELATIVE flag is used to indicate if templates specified with
filenames relative to the current directory (e.g. './foo/bar' or
'../../some/where/else') should be loaded. It is also disabled by
default, and will raise a 'file' error if such template names are
encountered.
</p>
<pre> my $template = Template->new({
RELATIVE => 1,
});</pre>
<pre> [% tt_start_tag %] INCLUDE ../logs/error.log [% tt_end_tag %]</pre>
<li><b>DEFAULT</b><br>
<p>
The DEFAULT option can be used to specify a default template which should
be used whenever a specified template can't be found in the INCLUDE_PATH.
</p>
<pre> my $template = Template->new({
DEFAULT => 'notfound.html',
});</pre>
<p>
If a non-existant template is requested through the Template process()
method, or by an INCLUDE, PROCESS or WRAPPER directive, then the
DEFAULT template will instead be processed, if defined. Note that the
DEFAULT template is not used when templates are specified with
absolute or relative filenames, or as a reference to a input file
handle or text string.
</p>
<li><b>BLOCKS</b><br>
<p>
The BLOCKS option can be used to pre-define a default set of template
blocks. These should be specified as a reference to a hash array
mapping template names to template text, subroutines or Template::Document
objects.
</p>
<pre> my $template = Template->new({
BLOCKS => {
header => 'The Header. [% tt_start_tag %] title [% tt_end_tag %]',
footer => sub { return $some_output_text },
another => Template::Document->new({ ... }),
},
}); </pre>
<li><b>AUTO_RESET</b><br>
<p>
The AUTO_RESET option is set by default and causes the local BLOCKS
cache for the Template::Context object to be reset on each call to the
Template process() method. This ensures that any BLOCKs defined
within a template will only persist until that template is finished
processing. This prevents BLOCKs defined in one processing request
from interfering with other independent requests subsequently
processed by the same context object.
</p>
<p>
The BLOCKS item may be used to specify a default set of block definitions
for the Template::Context object. Subsequent BLOCK definitions in templates
will over-ride these but they will be reinstated on each reset if AUTO_RESET
is enabled (default), or if the Template::Context reset() method is called.
</p>
<li><b>RECURSION</b><br>
<p>
The template processor will raise a file exception if it detects
direct or indirect recursion into a template. Setting this option to
any true value will allow templates to include each other recursively.
</p>
</ul>
[%- END %]
[% WRAPPER subsection
title = "Template Variables"
-%]<ul>
<li><b>VARIABLES, PRE_DEFINE</b><br>
<p>
The VARIABLES option (or PRE_DEFINE - they're equivalent) can be used
to specify a hash array of template variables that should be used to
pre-initialise the stash when it is created. These items are ignored
if the STASH item is defined.
</p>
<pre> my $template = Template->new({
VARIABLES => {
title => 'A Demo Page',
author => 'Joe Random Hacker',
version => 3.14,
},
};</pre>
<p>
or
</p>
<pre> my $template = Template->new({
PRE_DEFINE => {
title => 'A Demo Page',
author => 'Joe Random Hacker',
version => 3.14,
},
};</pre>
<li><b>CONSTANTS</b><br>
<p>
The CONSTANTS option can be used to specify a hash array of template
variables that are compile-time constants. These variables are
resolved once when the template is compiled, and thus don't require
further resolution at runtime. This results in significantly faster
processing of the compiled templates and can be used for variables that
don't change from one request to the next.
</p>
<pre> my $template = Template->new({
CONSTANTS => {
title => 'A Demo Page',
author => 'Joe Random Hacker',
version => 3.14,
},
};</pre>
<li><b>CONSTANT_NAMESPACE</b><br>
<p>
Constant variables are accessed via the 'constants' namespace by
default.
</p>
<pre> [% tt_start_tag %] constants.title [% tt_end_tag %]</pre>
<p>
The CONSTANTS_NAMESPACE option can be set to specify an alternate
namespace.
</p>
<pre> my $template = Template->new({
CONSTANTS => {
title => 'A Demo Page',
# ...etc...
},
CONSTANTS_NAMESPACE => 'const',
};</pre>
<p>
In this case the constants would then be accessed as:
</p>
<pre> [% tt_start_tag %] const.title [% tt_end_tag %]</pre>
<li><b>NAMESPACE</b><br>
<p>
The constant folding mechanism described above is an example of a
namespace handler. Namespace handlers can be defined to provide
alternate parsing mechanisms for variables in different namespaces.
</p>
<p>
Under the hood, the Template module converts a constructor configuration
such as:
</p>
<pre> my $template = Template->new({
CONSTANTS => {
title => 'A Demo Page',
# ...etc...
},
CONSTANTS_NAMESPACE => 'const',
};</pre>
<p>
into one like:
</p>
<pre> my $template = Template->new({
NAMESPACE => {
const => Template:::Namespace::Constants->new({
title => 'A Demo Page',
# ...etc...
}),
},
};</pre>
<p>
You can use this mechanism to define multiple constant namespaces, or
to install custom handlers of your own.
</p>
<pre> my $template = Template->new({
NAMESPACE => {
site => Template:::Namespace::Constants->new({
title => "Wardley's Widgets",
version => 2.718,
}),
author => Template:::Namespace::Constants->new({
name => 'Andy Wardley',
email => 'abw@andywardley.com',
}),
voodoo => My::Namespace::Handler->new( ... ),
},
};</pre>
<p>
Now you have 2 constant namespaces, for example:
</p>
<pre> [% tt_start_tag %] site.title [% tt_end_tag %]
[% tt_start_tag %] author.name [% tt_end_tag %]</pre>
<p>
as well as your own custom namespace handler installed for the 'voodoo'
namespace.
</p>
<pre> [% tt_start_tag %] voodoo.magic [% tt_end_tag %]</pre>
<p>
See [% ttlink('Template::Namespace::Constants', 'Template::Namespace::Constants') -%]
for an example of what a namespace handler looks like on the inside.
</p>
</ul>
[%- END %]
[% WRAPPER subsection
title = "Runtime Processing Options"
-%]<ul>
<li><b>EVAL_PERL</b><br>
<p>
This flag is used to indicate if PERL and/or RAWPERL blocks should be
evaluated. By default, it is disabled and any PERL or RAWPERL blocks
encountered will raise exceptions of type 'perl' with the message
'EVAL_PERL not set'. Note however that any RAWPERL blocks should
always contain valid Perl code, regardless of the EVAL_PERL flag. The
parser will fail to compile templates that contain invalid Perl code
in RAWPERL blocks and will throw a 'file' exception.
</p>
<p>
When using compiled templates (see
[% ttlink('Template::Manual::Config/Caching_and_Compiling_Options', 'COMPILE_EXT') -%] and
[% ttlink('Template::Manual::Config/Caching_and_Compiling_Options', 'COMPILE_DIR') -%]),
the EVAL_PERL has an affect when the template is compiled, and again
when the templates is subsequently processed, possibly in a different
context to the one that compiled it.
</p>
<p>
If the EVAL_PERL is set when a template is compiled, then all PERL and
RAWPERL blocks will be included in the compiled template. If the
EVAL_PERL option isn't set, then Perl code will be generated which
<b>always</b> throws a 'perl' exception with the message 'EVAL_PERL not
set' <b>whenever</b> the compiled template code is run.
</p>
<p>
Thus, you must have EVAL_PERL set if you want your compiled templates
to include PERL and RAWPERL blocks.
</p>
<p>
At some point in the future, using a different invocation of the
Template Toolkit, you may come to process such a pre-compiled
template. Assuming the EVAL_PERL option was set at the time the
template was compiled, then the output of any RAWPERL blocks will be
included in the compiled template and will get executed when the
template is processed. This will happen regardless of the runtime
EVAL_PERL status.
</p>
<p>
Regular PERL blocks are a little more cautious, however. If the
EVAL_PERL flag isn't set for the <i>current</i> context, that is, the
one which is trying to process it, then it will throw the familiar 'perl'
exception with the message, 'EVAL_PERL not set'.
</p>
<p>
Thus you can compile templates to include PERL blocks, but optionally
disable them when you process them later. Note however that it is
possible for a PERL block to contain a Perl "BEGIN { # some code }"
block which will always get run regardless of the runtime EVAL_PERL
status. Thus, if you set EVAL_PERL when compiling templates, it is
assumed that you trust the templates to Do The Right Thing. Otherwise
you must accept the fact that there's no bulletproof way to prevent
any included code from trampling around in the living room of the
runtime environment, making a real nuisance of itself if it really
wants to. If you don't like the idea of such uninvited guests causing
a bother, then you can accept the default and keep EVAL_PERL disabled.
</p>
<li><b>PRE_PROCESS, POST_PROCESS</b><br>
<p>
These values may be set to contain the name(s) of template files
(relative to INCLUDE_PATH) which should be processed immediately
before and/or after each template. These do not get added to
templates processed into a document via directives such as INCLUDE,
PROCESS, WRAPPER etc.
</p>
<pre> my $template = Template->new({
PRE_PROCESS => 'header',
POST_PROCESS => 'footer',
};</pre>
<p>
Multiple templates may be specified as a reference to a list. Each is
processed in the order defined.
</p>
<pre> my $template = Template->new({
PRE_PROCESS => [ 'config', 'header' ],
POST_PROCESS => 'footer',
};</pre>
<p>
Alternately, multiple template may be specified as a single string,
delimited by ':'. This delimiter string can be changed via the
DELIMITER option.
</p>
<pre> my $template = Template->new({
PRE_PROCESS => 'config:header',
POST_PROCESS => 'footer',
};</pre>
<p>
The PRE_PROCESS and POST_PROCESS templates are evaluated in the same
variable context as the main document and may define or update
variables for subsequent use.
</p>
<p>
config:
</p>
<pre> [% tt_start_tag %] # set some site-wide variables
bgcolor = '#ffffff'
version = 2.718
[% tt_end_tag %]</pre>
<p>
header:
</p>
<pre> [% tt_start_tag %] DEFAULT title = 'My Funky Web Site' [% tt_end_tag %]
<html>
<head>
<title>[% tt_start_tag %] title [% tt_end_tag %]</title>
</head>
<body bgcolor="[% tt_start_tag %] bgcolor [% tt_end_tag %]"></pre>
<p>
footer:
</p>
<pre> <hr>
Version [% tt_start_tag %] version [% tt_end_tag %]
</body>
</html></pre>
<p>
The Template::Document object representing the main template being processed
is available within PRE_PROCESS and POST_PROCESS templates as the 'template'
variable. Metadata items defined via the META directive may be accessed
accordingly.
</p>
<pre> $template->process('mydoc.html', $vars);</pre>
<p>
mydoc.html:
</p>
<pre> [% tt_start_tag %] META title = 'My Document Title' [% tt_end_tag %]
blah blah blah
...</pre>
<p>
header:
</p>
<pre> <html>
<head>
<title>[% tt_start_tag %] template.title [% tt_end_tag %]</title></head>
<body bgcolor="[% tt_start_tag %] bgcolor [% tt_end_tag %]"></pre>
<li><b>PROCESS</b><br>
<p>
The PROCESS option may be set to contain the name(s) of template files
(relative to INCLUDE_PATH) which should be processed instead of the
main template passed to the Template process() method. This can
be used to apply consistent wrappers around all templates, similar to
the use of PRE_PROCESS and POST_PROCESS templates.
</p>
<pre> my $template = Template->new({
PROCESS => 'content',
};</pre>
<pre> # processes 'content' instead of 'foo.html'
$template->process('foo.html');</pre>
<p>
A reference to the original template is available in the 'template'
variable. Metadata items can be inspected and the template can be
processed by specifying it as a variable reference (i.e. prefixed by
'$') to an INCLUDE, PROCESS or WRAPPER directive.
</p>
<p>
content:
</p>
<pre> <html>
<head>
<title>[% tt_start_tag %] template.title [% tt_end_tag %]</title>
</head>
<body>
[% tt_start_tag %] PROCESS $template [% tt_end_tag %]
<hr>
&copy; Copyright [% tt_start_tag %] template.copyright [% tt_end_tag %]
</body>
</html></pre>
<p>
foo.html:
</p>
<pre> [% tt_start_tag %] META
title = 'The Foo Page'
author = 'Fred Foo'
copyright = '2000 Fred Foo'
[% tt_end_tag %]
<h1>[% tt_start_tag %] template.title [% tt_end_tag %]</h1>
Welcome to the Foo Page, blah blah blah</pre>
<p>
output:
</p>
<pre> <html>
<head>
<title>The Foo Page</title>
</head></pre>
<pre> <body>
<h1>The Foo Page</h1>
Welcome to the Foo Page, blah blah blah
<hr>
&copy; Copyright 2000 Fred Foo
</body>
</html></pre>
<li><b>ERROR</b><br>
<p>
The ERROR (or ERRORS if you prefer) configuration item can be used to
name a single template or specify a hash array mapping exception types
to templates which should be used for error handling. If an uncaught
exception is raised from within a template then the appropriate error
template will instead be processed.
</p>
<p>
If specified as a single value then that template will be processed
for all uncaught exceptions.
</p>
<pre> my $template = Template->new({
ERROR => 'error.html'
});</pre>
<p>
If the ERROR item is a hash reference the keys are assumed to be
exception types and the relevant template for a given exception will
be selected. A 'default' template may be provided for the general
case. Note that 'ERROR' can be pluralised to 'ERRORS' if you find
it more appropriate in this case.
</p>
<pre> my $template = Template->new({
ERRORS => {
user => 'user/index.html',
dbi => 'error/database',
default => 'error/default',
},
});</pre>
<p>
In this example, any 'user' exceptions thrown will cause the
'user/index.html' template to be processed, 'dbi' errors are handled
by 'error/database' and all others by the 'error/default' template.
Any PRE_PROCESS and/or POST_PROCESS templates will also be applied
to these error templates.
</p>
<p>
Note that exception types are hierarchical and a 'foo' handler will
catch all 'foo.*' errors (e.g. foo.bar, foo.bar.baz) if a more
specific handler isn't defined. Be sure to quote any exception types
that contain periods to prevent Perl concatenating them into a single
string (i.e. <code>'user.passwd'</code> is parsed as 'user'.'passwd').
</p>
<pre> my $template = Template->new({
ERROR => {
'user.login' => 'user/login.html',
'user.passwd' => 'user/badpasswd.html',
'user' => 'user/index.html',
'default' => 'error/default',
},
});</pre>
<p>
In this example, any template processed by the $template object, or
other templates or code called from within, can raise a 'user.login'
exception and have the service redirect to the 'user/login.html'
template. Similarly, a 'user.passwd' exception has a specific
handling template, 'user/badpasswd.html', while all other 'user' or
'user.*' exceptions cause a redirection to the 'user/index.html' page.
All other exception types are handled by 'error/default'.
</p>
<p>
Exceptions can be raised in a template using the THROW directive,
</p>
<pre> [% tt_start_tag %] THROW user.login 'no user id: please login' [% tt_end_tag %]</pre>
<p>
or by calling the throw() method on the current Template::Context object,
</p>
<pre> $context->throw('user.passwd', 'Incorrect Password');
$context->throw('Incorrect Password'); # type 'undef'</pre>
<p>
or from Perl code by calling die() with a Template::Exception object,
</p>
<pre> die Template::Exception->new('user.denied', 'Invalid User ID');</pre>
<p>
or by simply calling die() with an error string. This is
automagically caught and converted to an exception of 'undef'
type which can then be handled in the usual way.
</p>
<pre> die "I'm sorry Dave, I can't do that";</pre>
<li><b>OUTPUT</b><br>
<p>
Default output location or handler. This may be specified as one of:
a file name (relative to OUTPUT_PATH, if defined, or the current
working directory if not specified absolutely); a file handle
(e.g. GLOB or IO::Handle) opened for writing; a reference to a text
string to which the output is appended (the string isn't cleared); a
reference to a subroutine which is called, passing the output text as
an argument; as a reference to an array, onto which the content will be
push()ed; or as a reference to any object that supports the print()
method. This latter option includes the Apache::Request object which
is passed as the argument to Apache/mod_perl handlers.
</p>
<p>
example 1 (file name):
</p>
<pre> my $template = Template->new({
OUTPUT => "/tmp/foo",
});</pre>
<p>
example 2 (text string):
</p>
<pre> my $output = '';</pre>
<pre> my $template = Template->new({
OUTPUT => \$output,
});</pre>
<p>
example 3 (file handle):
</p>
<pre> open (TOUT, "> $file") || die "$file: $!\n";</pre>
<pre> my $template = Template->new({
OUTPUT => \*TOUT,
});</pre>
<p>
example 4 (subroutine):
</p>
<pre> sub output { my $out = shift; print "OUTPUT: $out" }</pre>
<pre> my $template = Template->new({
OUTPUT => \&output,
});</pre>
<p>
example 5 (array reference):
</p>
<pre> my $template = Template->new({
OUTPUT => \@output,
})</pre>
<p>
example 6 (Apache/mod_perl handler):
</p>
<pre> sub handler {
my $r = shift;</pre>
<pre> my $t = Template->new({
OUTPUT => $r,
});
...
}</pre>
<p>
The default OUTPUT location be overridden by passing a third parameter
to the Template process() method. This can be specified as any of the
above argument types.
</p>
<pre> $t->process($file, $vars, "/tmp/foo");
$t->process($file, $vars, "bar");
$t->process($file, $vars, \*MYGLOB);
$t->process($file, $vars, \@output);
$t->process($file, $vars, $r); # Apache::Request
...</pre>
<li><b>OUTPUT_PATH</b><br>
<p>
The OUTPUT_PATH allows a directory to be specified into which output
files should be written. An output file can be specified by the
OUTPUT option, or passed by name as the third parameter to the
Template process() method.
</p>
<pre> my $template = Template->new({
INCLUDE_PATH => "/tmp/src",
OUTPUT_PATH => "/tmp/dest",
});</pre>
<pre> my $vars = {
...
};</pre>
<pre> foreach my $file ('foo.html', 'bar.html') {
$template->process($file, $vars, $file)
|| die $template->error();
}</pre>
<p>
This example will read the input files '/tmp/src/foo.html' and
'/tmp/src/bar.html' and write the processed output to '/tmp/dest/foo.html'
and '/tmp/dest/bar.html', respectively.
</p>
<li><b>DEBUG</b><br>
<p>
The DEBUG option enables debugging within the Template Toolkit.
</p>
<pre> my $template = Template->new({
DEBUG => 1,
});</pre>
<p>
Setting this to a true value has two effects. The first is that
accessing any variable that returns an undefined variable will cause
an 'undef' error to be raised.
</p>
<p>
The second is that the output generated by the Template Toolkit will
have comments added indicating the source file, line and original text
of each directive in the template.
</p>
<p>
For example, the following template fragment:
</p>
<pre> [% tt_start_tag %] foo = 'World' [% tt_end_tag %]
Hello [% tt_start_tag %] foo [% tt_end_tag %]</pre>
<p>
would generate this output:
</p>
<pre> ## input text line 1 : [% tt_start_tag %] foo = 'World' [% tt_end_tag %] ##
Hello
## input text line 2 : [% tt_start_tag %] foo [% tt_end_tag %] ##
World</pre>
<p>
The DEBUG directive can be used to enable and disable directive
debugging at different parts of a template. The DEBUG constructor
option must be set for the DEBUG directive to have any effect.
</p>
<pre> [% tt_start_tag %] DEBUG on [% tt_end_tag %]
[% tt_start_tag %] foo = 'World' [% tt_end_tag %]
[% tt_start_tag %] DEBUG off [% tt_end_tag %]
Hello [% tt_start_tag %] foo [% tt_end_tag %]</pre>
<p>
This template fragment would generate the following output:
</p>
<pre> ## input text line 1 : [% tt_start_tag %] foo = 'World' [% tt_end_tag %] ##
Hello World</pre>
<p>
It is anticipated that a future version of the Template Toolkit will
support allow the different debugging options to be enabled or
disabled individually.
</p>
<li><b>DEBUG_FORMAT</b><br>
<p>
The DEBUG_FORMAT option can be used to specify a format string for the
debugging messages described in the DEBUG option above. Any
occurances of <code>'$file'</code>, <code>'$line'</code> or <code>'$text'</code> will be replaced with the
current file name, line or directive text, respectively. Notice how
the format is single quoted to prevent Perl from interpolating those
tokens as variables.
</p>
<pre> my $template = Template->new({
DEBUG => 1,
DEBUG_FORMAT => '<!-- $file line $line : [% tt_start_tag %] $text [% tt_end_tag %] -->',
});</pre>
<p>
The following template fragment:
</p>
<pre> [% tt_start_tag %] DEBUG on [% tt_end_tag %]
[% tt_start_tag %] foo = 'World' [% tt_end_tag %]
Hello [% tt_start_tag %] foo [% tt_end_tag %]</pre>
<p>
would then generate this output:
</p>
<pre> <!-- input text line 2 : [% tt_start_tag %] foo = 'World' [% tt_end_tag %] -->
Hello <!-- input text line 3 : [% tt_start_tag %] foo [% tt_end_tag %] -->World</pre>
<p>
The DEBUG directive can also be used to set a debug format within
a template.
</p>
<pre> [% tt_start_tag %] DEBUG format '<!-- $file line $line : [% tt_start_tag %] $text [% tt_end_tag %] -->' [% tt_end_tag %]</pre>
<pre> </pre>
</ul>
[%- END %]
[% WRAPPER subsection
title = "Caching and Compiling Options"
-%]<ul>
<li><b>CACHE_SIZE</b><br>
<p>
The Template::Provider module caches compiled templates to avoid the need
to re-parse template files or blocks each time they are used. The CACHE_SIZE
option is used to limit the number of compiled templates that the module
should cache.
</p>
<p>
By default, the CACHE_SIZE is undefined and all compiled templates are
cached. When set to any positive value, the cache will be limited to
storing no more than that number of compiled templates. When a new
template is loaded and compiled and the cache is full (i.e. the number
of entries == CACHE_SIZE), the least recently used compiled template
is discarded to make room for the new one.
</p>
<p>
The CACHE_SIZE can be set to 0 to disable caching altogether.
</p>
<pre> my $template = Template->new({
CACHE_SIZE => 64, # only cache 64 compiled templates
});</pre>
<pre> my $template = Template->new({
CACHE_SIZE => 0, # don't cache any compiled templates
});</pre>
<li><b>COMPILE_EXT</b><br>
<p>
From version 2 onwards, the Template Toolkit has the ability to
compile templates to Perl code and save them to disk for subsequent
use (i.e. cache persistence). The COMPILE_EXT option may be
provided to specify a filename extension for compiled template files.
It is undefined by default and no attempt will be made to read or write
any compiled template files.
</p>
<pre> my $template = Template->new({
COMPILE_EXT => '.ttc',
});</pre>
<p>
If COMPILE_EXT is defined (and COMPILE_DIR isn't, see below) then compiled
template files with the COMPILE_EXT extension will be written to the same
directory from which the source template files were loaded.
</p>
<p>
Compiling and subsequent reuse of templates happens automatically
whenever the COMPILE_EXT or COMPILE_DIR options are set. The Template
Toolkit will automatically reload and reuse compiled files when it
finds them on disk. If the corresponding source file has been modified
since the compiled version as written, then it will load and re-compile
the source and write a new compiled version to disk.
</p>
<p>
This form of cache persistence offers significant benefits in terms of
time and resources required to reload templates. Compiled templates can
be reloaded by a simple call to Perl's require(), leaving Perl to handle
all the parsing and compilation. This is a Good Thing.
</p>
<li><b>COMPILE_DIR</b><br>
<p>
The COMPILE_DIR option is used to specify an alternate directory root
under which compiled template files should be saved.
</p>
<pre> my $template = Template->new({
COMPILE_DIR => '/tmp/ttc',
});</pre>
<p>
The COMPILE_EXT option may also be specified to have a consistent file
extension added to these files.
</p>
<pre> my $template1 = Template->new({
COMPILE_DIR => '/tmp/ttc',
COMPILE_EXT => '.ttc1',
});</pre>
<pre> my $template2 = Template->new({
COMPILE_DIR => '/tmp/ttc',
COMPILE_EXT => '.ttc2',
});</pre>
<p>
When COMPILE_EXT is undefined, the compiled template files have the
same name as the original template files, but reside in a different
directory tree.
</p>
<p>
Each directory in the INCLUDE_PATH is replicated in full beneath the
COMPILE_DIR directory. This example:
</p>
<pre> my $template = Template->new({
COMPILE_DIR => '/tmp/ttc',
INCLUDE_PATH => '/home/abw/templates:/usr/share/templates',
});</pre>
<p>
would create the following directory structure:
</p>
<pre> /tmp/ttc/home/abw/templates/
/tmp/ttc/usr/share/templates/</pre>
<p>
Files loaded from different INCLUDE_PATH directories will have their
compiled forms save in the relevant COMPILE_DIR directory.
</p>
<p>
On Win32 platforms a filename may by prefixed by a drive letter and
colon. e.g.
</p>
<pre> C:/My Templates/header</pre>
<p>
The colon will be silently stripped from the filename when it is added
to the COMPILE_DIR value(s) to prevent illegal filename being generated.
Any colon in COMPILE_DIR elements will be left intact. For example:
</p>
<pre> # Win32 only
my $template = Template->new({
DELIMITER => ';',
COMPILE_DIR => 'C:/TT2/Cache',
INCLUDE_PATH => 'C:/TT2/Templates;D:/My Templates',
});</pre>
<p>
This would create the following cache directories:
</p>
<pre> C:/TT2/Cache/C/TT2/Templates
C:/TT2/Cache/D/My Templates</pre>
</ul>
[%- END %]
[% WRAPPER subsection
title = "Plugins and Filters"
-%]<ul>
<li><b>PLUGINS</b><br>
<p>
The PLUGINS options can be used to provide a reference to a hash array
that maps plugin names to Perl module names. A number of standard
plugins are defined (e.g. 'table', 'cgi', 'dbi', etc.) which map to
their corresponding Template::Plugin::* counterparts. These can be
redefined by values in the PLUGINS hash.
</p>
<pre> my $template = Template->new({
PLUGINS => {
cgi => 'MyOrg::Template::Plugin::CGI',
foo => 'MyOrg::Template::Plugin::Foo',
bar => 'MyOrg::Template::Plugin::Bar',
},
});</pre>
<p>
The USE directive is used to create plugin objects and does so by
calling the plugin() method on the current Template::Context object.
If the plugin name is defined in the PLUGINS hash then the
corresponding Perl module is loaded via require(). The context then
calls the load() class method which should return the class name
(default and general case) or a prototype object against which the
new() method can be called to instantiate individual plugin objects.
</p>
<p>
If the plugin name is not defined in the PLUGINS hash then the PLUGIN_BASE
and/or LOAD_PERL options come into effect.
</p>
<li><b>PLUGIN_BASE</b><br>
<p>
If a plugin is not defined in the PLUGINS hash then the PLUGIN_BASE is used
to attempt to construct a correct Perl module name which can be successfully
loaded.
</p>
<p>
The PLUGIN_BASE can be specified as a single value or as a reference
to an array of multiple values. The default PLUGIN_BASE value,
'Template::Plugin', is always added the the end of the PLUGIN_BASE
list (a single value is first converted to a list). Each value should
contain a Perl package name to which the requested plugin name is
appended.
</p>
<p>
example 1:
</p>
<pre> my $template = Template->new({
PLUGIN_BASE => 'MyOrg::Template::Plugin',
});</pre>
<pre> [% tt_start_tag %] USE Foo [% tt_end_tag %] # => MyOrg::Template::Plugin::Foo
or Template::Plugin::Foo </pre>
<p>
example 2:
</p>
<pre> my $template = Template->new({
PLUGIN_BASE => [ 'MyOrg::Template::Plugin',
'YourOrg::Template::Plugin' ],
});</pre>
<pre> [% tt_start_tag %] USE Foo [% tt_end_tag %] # => MyOrg::Template::Plugin::Foo
or YourOrg::Template::Plugin::Foo
or Template::Plugin::Foo </pre>
<li><b>LOAD_PERL</b><br>
<p>
If a plugin cannot be loaded using the PLUGINS or PLUGIN_BASE
approaches then the provider can make a final attempt to load the
module without prepending any prefix to the module path. This allows
regular Perl modules (i.e. those that don't reside in the
Template::Plugin or some other such namespace) to be loaded and used
as plugins.
</p>
<p>
By default, the LOAD_PERL option is set to 0 and no attempt will be made
to load any Perl modules that aren't named explicitly in the PLUGINS
hash or reside in a package as named by one of the PLUGIN_BASE
components.
</p>
<p>
Plugins loaded using the PLUGINS or PLUGIN_BASE receive a reference to
the current context object as the first argument to the new()
constructor. Modules loaded using LOAD_PERL are assumed to not
conform to the plugin interface. They must provide a new() class
method for instantiating objects but it will not receive a reference
to the context as the first argument. Plugin modules should provide a
load() class method (or inherit the default one from the
Template::Plugin base class) which is called the first time the plugin
is loaded. Regular Perl modules need not. In all other respects,
regular Perl objects and Template Toolkit plugins are identical.
</p>
<p>
If a particular Perl module does not conform to the common, but not
unilateral, new() constructor convention then a simple plugin wrapper
can be written to interface to it.
</p>
<li><b>FILTERS</b><br>
<p>
The FILTERS option can be used to specify custom filters which can
then be used with the FILTER directive like any other. These are
added to the standard filters which are available by default. Filters
specified via this option will mask any standard filters of the same
name.
</p>
<p>
The FILTERS option should be specified as a reference to a hash array
in which each key represents the name of a filter. The corresponding
value should contain a reference to an array containing a subroutine
reference and a flag which indicates if the filter is static (0) or
dynamic (1). A filter may also be specified as a solitary subroutine
reference and is assumed to be static.
</p>
<pre> $template = Template->new({
FILTERS => {
'sfilt1' => \&static_filter, # static
'sfilt2' => [ \&static_filter, 0 ], # same as above
'dfilt1' => [ \&dyanamic_filter_factory, 1 ],
},
});</pre>
<p>
Additional filters can be specified at any time by calling the
define_filter() method on the current Template::Context object.
The method accepts a filter name, a reference to a filter
subroutine and an optional flag to indicate if the filter is
dynamic.
</p>
<pre> my $context = $template->context();
$context->define_filter('new_html', \&new_html);
$context->define_filter('new_repeat', \&new_repeat, 1);</pre>
<p>
Static filters are those where a single subroutine reference is used
for all invocations of a particular filter. Filters that don't accept
any configuration parameters (e.g. 'html') can be implemented
statically. The subroutine reference is simply returned when that
particular filter is requested. The subroutine is called to filter
the output of a template block which is passed as the only argument.
The subroutine should return the modified text.
</p>
<pre> sub static_filter {
my $text = shift;
# do something to modify $text...
return $text;
}</pre>
<p>
The following template fragment:
</p>
<pre> [% tt_start_tag %] FILTER sfilt1 [% tt_end_tag %]
Blah blah blah.
[% tt_start_tag %] END [% tt_end_tag %]</pre>
<p>
is approximately equivalent to:
</p>
<pre> &static_filter("\nBlah blah blah.\n");</pre>
<p>
Filters that can accept parameters (e.g. 'truncate') should be
implemented dynamically. In this case, the subroutine is taken to be
a filter 'factory' that is called to create a unique filter subroutine
each time one is requested. A reference to the current
Template::Context object is passed as the first parameter, followed by
any additional parameters specified. The subroutine should return
another subroutine reference (usually a closure) which implements the
filter.
</p>
<pre> sub dynamic_filter_factory {
my ($context, @args) = @_;</pre>
<pre> return sub {
my $text = shift;
# do something to modify $text...
return $text;
}
}</pre>
<p>
The following template fragment:
</p>
<pre> [% tt_start_tag %] FILTER dfilt1(123, 456) [% tt_end_tag %]
Blah blah blah
[% tt_start_tag %] END [% tt_end_tag %] </pre>
<p>
is approximately equivalent to:
</p>
<pre> my $filter = &dynamic_filter_factory($context, 123, 456);
&$filter("\nBlah blah blah.\n");</pre>
<p>
See the FILTER directive for further examples.
</p>
</ul>
[%- END %]
[% WRAPPER subsection
title = "Compatibility, Customisation and Extension"
-%]<ul>
<li><b>V1DOLLAR</b><br>
<p>
In version 1 of the Template Toolkit, an optional leading '$' could be placed
on any template variable and would be silently ignored.
</p>
<pre> # VERSION 1
[% tt_start_tag %] $foo [% tt_end_tag %] === [% tt_start_tag %] foo [% tt_end_tag %]
[% tt_start_tag %] $hash.$key [% tt_end_tag %] === [% tt_start_tag %] hash.key [% tt_end_tag %]</pre>
<p>
To interpolate a variable value the '${' ... '}' construct was used.
Typically, one would do this to index into a hash array when the key
value was stored in a variable.
</p>
<p>
example:
</p>
<pre> my $vars = {
users => {
aba => { name => 'Alan Aardvark', ... },
abw => { name => 'Andy Wardley', ... },
...
},
uid => 'aba',
...
};</pre>
<pre> $template->process('user/home.html', $vars)
|| die $template->error(), "\n";</pre>
<p>
'user/home.html':
</p>
<pre> [% tt_start_tag %] user = users.${uid} [% tt_end_tag %] # users.aba
Name: [% tt_start_tag %] user.name [% tt_end_tag %] # Alan Aardvark</pre>
<p>
This was inconsistent with double quoted strings and also the
INTERPOLATE mode, where a leading '$' in text was enough to indicate a
variable for interpolation, and the additional curly braces were used
to delimit variable names where necessary. Note that this use is
consistent with UNIX and Perl conventions, among others.
</p>
<pre> # double quoted string interpolation
[% tt_start_tag %] name = "$title ${user.name}" [% tt_end_tag %]</pre>
<pre> # INTERPOLATE = 1
<img src="$images/help.gif"></a>
<img src="$images/${icon.next}.gif"></pre>
<p>
For version 2, these inconsistencies have been removed and the syntax
clarified. A leading '$' on a variable is now used exclusively to
indicate that the variable name should be interpolated
(e.g. subsituted for its value) before being used. The earlier example
from version 1:
</p>
<pre> # VERSION 1
[% tt_start_tag %] user = users.${uid} [% tt_end_tag %]
Name: [% tt_start_tag %] user.name [% tt_end_tag %]</pre>
<p>
can now be simplified in version 2 as:
</p>
<pre> # VERSION 2
[% tt_start_tag %] user = users.$uid [% tt_end_tag %]
Name: [% tt_start_tag %] user.name [% tt_end_tag %]</pre>
<p>
The leading dollar is no longer ignored and has the same effect of
interpolation as '${' ... '}' in version 1. The curly braces may
still be used to explicitly scope the interpolated variable name
where necessary.
</p>
<p>
e.g.
</p>
<pre> [% tt_start_tag %] user = users.${me.id} [% tt_end_tag %]
Name: [% tt_start_tag %] user.name [% tt_end_tag %]</pre>
<p>
The rule applies for all variables, both within directives and in
plain text if processed with the INTERPOLATE option. This means that
you should no longer (if you ever did) add a leading '$' to a variable
inside a directive, unless you explicitly want it to be interpolated.
</p>
<p>
One obvious side-effect is that any version 1 templates with variables
using a leading '$' will no longer be processed as expected. Given
the following variable definitions,
</p>
<pre> [% tt_start_tag %] foo = 'bar'
bar = 'baz'
[% tt_end_tag %]</pre>
<p>
version 1 would interpret the following as:
</p>
<pre> # VERSION 1
[% tt_start_tag %] $foo [% tt_end_tag %] => [% tt_start_tag %] GET foo [% tt_end_tag %] => bar</pre>
<p>
whereas version 2 interprets it as:
</p>
<pre> # VERSION 2
[% tt_start_tag %] $foo [% tt_end_tag %] => [% tt_start_tag %] GET $foo [% tt_end_tag %] => [% tt_start_tag %] GET bar [% tt_end_tag %] => baz</pre>
<p>
In version 1, the '$' is ignored and the value for the variable 'foo' is
retrieved and printed. In version 2, the variable '$foo' is first interpolated
to give the variable name 'bar' whose value is then retrieved and printed.
</p>
<p>
The use of the optional '$' has never been strongly recommended, but
to assist in backwards compatibility with any version 1 templates that
may rely on this "feature", the V1DOLLAR option can be set to 1
(default: 0) to revert the behaviour and have leading '$' characters
ignored.
</p>
<pre> my $template = Template->new({
V1DOLLAR => 1,
});</pre>
<li><b>LOAD_TEMPLATES</b><br>
<p>
The LOAD_TEMPLATE option can be used to provide a reference to a list
of Template::Provider objects or sub-classes thereof which will take
responsibility for loading and compiling templates.
</p>
<pre> my $template = Template->new({
LOAD_TEMPLATES => [
MyOrg::Template::Provider->new({ ... }),
Template::Provider->new({ ... }),
],
});</pre>
<p>
When a PROCESS, INCLUDE or WRAPPER directive is encountered, the named
template may refer to a locally defined BLOCK or a file relative to
the INCLUDE_PATH (or an absolute or relative path if the appropriate
ABSOLUTE or RELATIVE options are set). If a BLOCK definition can't be
found (see the Template::Context template() method for a discussion of
BLOCK locality) then each of the LOAD_TEMPLATES provider objects is
queried in turn via the fetch() method to see if it can supply the
required template. Each provider can return a compiled template, an
error, or decline to service the request in which case the
responsibility is passed to the next provider. If none of the
providers can service the request then a 'not found' error is
returned. The same basic provider mechanism is also used for the
INSERT directive but it bypasses any BLOCK definitions and doesn't
attempt is to parse or process the contents of the template file.
</p>
<p>
This is an implementation of the 'Chain of Responsibility'
design pattern as described in
"Design Patterns", Erich Gamma, Richard Helm, Ralph Johnson, John
Vlissides), Addision-Wesley, ISBN 0-201-63361-2, page 223
.
</p>
<p>
If LOAD_TEMPLATES is undefined, a single default provider will be
instantiated using the current configuration parameters. For example,
the Template::Provider INCLUDE_PATH option can be specified in the Template configuration and will be correctly passed to the provider's
constructor method.
</p>
<pre> my $template = Template->new({
INCLUDE_PATH => '/here:/there',
});</pre>
<li><b>LOAD_PLUGINS</b><br>
<p>
The LOAD_PLUGINS options can be used to specify a list of provider
objects (i.e. they implement the fetch() method) which are responsible
for loading and instantiating template plugin objects. The
Template::Content plugin() method queries each provider in turn in a
"Chain of Responsibility" as per the template() and filter() methods.
</p>
<pre> my $template = Template->new({
LOAD_PLUGINS => [
MyOrg::Template::Plugins->new({ ... }),
Template::Plugins->new({ ... }),
],
});</pre>
<p>
By default, a single Template::Plugins object is created using the
current configuration hash. Configuration items destined for the
Template::Plugins constructor may be added to the Template
constructor.
</p>
<pre> my $template = Template->new({
PLUGIN_BASE => 'MyOrg::Template::Plugins',
LOAD_PERL => 1,
});</pre>
<li><b>LOAD_FILTERS</b><br>
<p>
The LOAD_FILTERS option can be used to specify a list of provider
objects (i.e. they implement the fetch() method) which are responsible
for returning and/or creating filter subroutines. The
Template::Context filter() method queries each provider in turn in a
"Chain of Responsibility" as per the template() and plugin() methods.
</p>
<pre> my $template = Template->new({
LOAD_FILTERS => [
MyTemplate::Filters->new(),
Template::Filters->new(),
],
});</pre>
<p>
By default, a single Template::Filters object is created for the
LOAD_FILTERS list.
</p>
<li><b>TOLERANT</b><br>
<p>
The TOLERANT flag is used by the various Template Toolkit provider
modules (Template::Provider, Template::Plugins, Template::Filters) to
control their behaviour when errors are encountered. By default, any
errors are reported as such, with the request for the particular
resource (template, plugin, filter) being denied and an exception
raised. When the TOLERANT flag is set to any true values, errors will
be silently ignored and the provider will instead return
STATUS_DECLINED. This allows a subsequent provider to take
responsibility for providing the resource, rather than failing the
request outright. If all providers decline to service the request,
either through tolerated failure or a genuine disinclination to
comply, then a '<resource> not found' exception is raised.
</p>
<li><b>SERVICE</b><br>
<p>
A reference to a Template::Service object, or sub-class thereof, to which
the Template module should delegate. If unspecified, a Template::Service
object is automatically created using the current configuration hash.
</p>
<pre> my $template = Template->new({
SERVICE => MyOrg::Template::Service->new({ ... }),
});</pre>
<li><b>CONTEXT</b><br>
<p>
A reference to a Template::Context object which is used to define a
specific environment in which template are processed. A Template::Context
object is passed as the only parameter to the Perl subroutines that
represent "compiled" template documents. Template subroutines make
callbacks into the context object to access Template Toolkit functionality,
for example, to to INCLUDE or PROCESS another template (include() and
process() methods, respectively), to USE a plugin (plugin()) or
instantiate a filter (filter()) or to access the stash (stash()) which
manages variable definitions via the get() and set() methods.
</p>
<pre> my $template = Template->new({
CONTEXT => MyOrg::Template::Context->new({ ... }),
});</pre>
<li><b>STASH</b><br>
<p>
A reference to a Template::Stash object or sub-class which will take
responsibility for managing template variables.
</p>
<pre> my $stash = MyOrg::Template::Stash->new({ ... });
my $template = Template->new({
STASH => $stash,
});</pre>
<p>
If unspecified, a default stash object is created using the VARIABLES
configuration item to initialise the stash variables. These may also
be specified as the PRE_DEFINE option for backwards compatibility with
version 1.
</p>
<pre> my $template = Template->new({
VARIABLES => {
id => 'abw',
name => 'Andy Wardley',
},
};</pre>
<li><b>PARSER</b><br>
<p>
The Template::Parser module implements a parser object for compiling
templates into Perl code which can then be executed. A default object
of this class is created automatically and then used by the
Template::Provider whenever a template is loaded and requires
compilation. The PARSER option can be used to provide a reference to
an alternate parser object.
</p>
<pre> my $template = Template->new({
PARSER => MyOrg::Template::Parser->new({ ... }),
});</pre>
<li><b>GRAMMAR</b><br>
<p>
The GRAMMAR configuration item can be used to specify an alternate
grammar for the parser. This allows a modified or entirely new
template language to be constructed and used by the Template Toolkit.
</p>
<p>
Source templates are compiled to Perl code by the Template::Parser
using the Template::Grammar (by default) to define the language
structure and semantics. Compiled templates are thus inherently
"compatible" with each other and there is nothing to prevent any
number of different template languages being compiled and used within
the same Template Toolkit processing environment (other than the usual
time and memory constraints).
</p>
<p>
The Template::Grammar file is constructed from a YACC like grammar
(using Parse::YAPP) and a skeleton module template. These files are
provided, along with a small script to rebuild the grammar, in the
'parser' sub-directory of the distribution. You don't have to know or
worry about these unless you want to hack on the template language or
define your own variant. There is a README file in the same directory
which provides some small guidance but it is assumed that you know
what you're doing if you venture herein. If you grok LALR parsers,
then you should find it comfortably familiar.
</p>
<p>
By default, an instance of the default Template::Grammar will be
created and used automatically if a GRAMMAR item isn't specified.
</p>
<pre> use MyOrg::Template::Grammar;</pre>
<pre> my $template = Template->new({
GRAMMAR = MyOrg::Template::Grammar->new();
});</pre>
</ul>
[%- END %]
[%- END %]
[% WRAPPER section
title="AUTHOR"
-%]<p>
Andy Wardley <abw@andywardley.com>
</p>
<p>
[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
Template Toolkit version 2.08, released on 30 July 2002.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
-%]<pre> Copyright (C) 1996-2002 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
</p>
[%- END %]