Template::Manual::Config - Configuration options |
Template::Manual::Config - Configuration options
The ENCODING
option specifies the template files' character encoding:
my $template = Template->new({ END_TAG => 'utf8', });
A template which starts with a Unicode byte order mark (BOM) will have its encoding detected automatically.
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
'[%
' and '%]
' respectively, giving us the familiar directive style:
[% example %]
Any Perl regex characters can be used and therefore should be escaped
(or use the Perl quotemeta
function) if they are intended to
represent literal characters.
my $template = Template->new({ START_TAG => quotemeta('<+'), END_TAG => quotemeta('+>'), });
Example:
<+ INCLUDE foobar +>
The TAGS
directive can also be used to set the START_TAG
and END_TAG
values
on a per-template file basis.
[% TAGS <+ +> %]
The TAG_STYLE
option can be used to set both START_TAG
and END_TAG
according to pre-defined tag styles.
my $template = Template->new({ TAG_STYLE => 'star', });
Available styles are:
template [% ... %] (default) template1 [% ... %] or %% ... %% (TT version 1) metatext %% ... %% (Text::MetaText) star [* ... *] (TT alternate) php <? ... ?> (PHP) asp <% ... %> (ASP) mason <% ... > (HTML::Mason) html <!-- ... --> (HTML comments)
Any values specified for START_TAG
and/or END_TAG
will override
those defined by a TAG_STYLE
.
The TAGS
directive may also be used to set a TAG_STYLE
[% TAGS html %] <!-- INCLUDE header -->
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.
Example:
Foo [% a = 10 %] Bar
Output:
Foo Bar
The PRE_CHOMP
and POST_CHOMP
options can help to clean up some of this
extraneous whitespace. Both are disabled by default.
my $template = Template-E<gt>new({ PRE_CHOMP => 1, POST_CHOMP => 1, });
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.
Foo <----------. | ,---(PRE_CHOMP)----' | `-- [% a = 10 %] --. | ,---(POST_CHOMP)---' | `-> Bar
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.
If PRE_CHOMP
or POST_CHOMP
is set to 2
, all whitespace including any
number of newline will be removed and replaced with a single space.
This is useful for HTML, where (usually) a contiguous block of
whitespace is rendered the same as a single space.
With PRE_CHOMP
or POST_CHOMP
set to 3
, all adjacent whitespace
(including newlines) will be removed entirely.
These values are defined as CHOMP_NONE
, CHOMP_ONE
, CHOMP_COLLAPSE
and
CHOMP_GREEDY
constants in the the Template::Constants manpage module. CHOMP_ALL
is also defined as an alias for CHOMP_ONE
to provide backwards
compatibility with earlier version of the Template Toolkit.
Additionally the chomp tag modifiers listed below may also be used for
the PRE_CHOMP
and POST_CHOMP
configuration.
my $template = Template->new({ PRE_CHOMP => '~', POST_CHOMP => '-', });
PRE_CHOMP
and POST_CHOMP
can be activated for individual directives by
placing a '-
' immediately at the start and/or end of the directive.
[% FOREACH user IN userlist %] [%- user -%] [% END %]
This has the same effect as CHOMP_ONE
in removing all whitespace
before or after the directive up to and including the newline. The
template will be processed as if written:
[% FOREACH user IN userlist %][% user %][% END %]
To remove all whitespace including any number of newlines, use the '~
'
character instead.
[% FOREACH user IN userlist %] [%~ user ~%] [% END %]
To collapse all whitespace to a single space, use the '=
' character.
[% FOREACH user IN userlist %] [%= user =%] [% END %]
Here the template is processed as if written:
[% FOREACH user IN userlist %] [% user %] [% END %]
If you have PRE_CHOMP
or POST_CHOMP
set as configuration options then
you can use '+
' to disable any chomping options (i.e. leave the
whitespace intact) on a per-directive basis.
[% FOREACH user IN userlist %] User: [% user +%] [% END %]
With POST_CHOMP
set to CHOMP_ONE
, the above example would be parsed as
if written:
[% FOREACH user IN userlist %]User: [% user %] [% END %]
For reference, the PRE_CHOMP
and POST_CHOMP
configuration options may be
set to any of the following:
Constant Value Tag Modifier ---------------------------------- CHOMP_NONE 0 + CHOMP_ONE 1 - CHOMP_COLLAPSE 2 = CHOMP_GREEDY 3 ~
The TRIM
option can be set to have any leading and trailing whitespace
automatically removed from the output of all template files and BLOCK
s.
By example, the following BLOCK
definition
[% BLOCK foo %] Line 1 of foo [% END %]
will be processed is as ``\nLine 1 of foo\n
''. When INCLUDE
d, the surrounding
newlines will also be introduced.
before [% INCLUDE foo %] after
Generated output:
before Line 1 of foo after
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
.
before Line 1 of foo after
The TRIM
option is disabled (0
) by default.
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.
my $template = Template->new({ INTERPOLATE => 1, });
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.
# INTERPOLATE => 0 <a href="http://[% server %]/[% help %]"> <img src="[% images %]/help.gif"></a> [% myorg.name %]
# INTERPOLATE => 1 <a href="http://$server/$help"> <img src="$images/help.gif"></a> $myorg.name # explicit scoping with { } <img src="$images/${icon.next}.gif">
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
.
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.
# ANYCASE => 0 (default) [% INCLUDE foobar %] # OK [% include foobar %] # ERROR [% include = 10 %] # OK, 'include' is a variable
# ANYCASE => 1 [% INCLUDE foobar %] # OK [% include foobar %] # OK [% include = 10 %] # ERROR, 'include' is reserved word
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:
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
The only lower case reserved words that cannot be used for variables,
regardless of the ANYCASE
option, are the operators:
and or not mod div
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 ':
'.
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' ], });
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
'.
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.
my $template = Template->new({ INCLUDE_PATH => [ '/usr/local/templates', \&incpath_generator, My::IncPath::Generator->new( ... ) ], });
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.
For example:
sub incpath_generator { # ...some code... if ($all_is_well) { return \@list_of_directories; } else { die "cannot generate INCLUDE_PATH...\n"; } }
or:
package My::IncPath::Generator; # Template::Base (or Class::Base) provides error() method use Template::Base; use base qw( Template::Base ); sub paths { my $self = shift; # ...some code... if ($all_is_well) { return \@list_of_directories; } else { return $self->error("cannot generate INCLUDE_PATH...\n"); } } 1;
Used to provide an alternative delimiter character sequence for
separating paths specified in the INCLUDE_PATH
. The default
value for DELIMITER
is ':
'.
my $template = Template->new({ DELIMITER => '; ', INCLUDE_PATH => 'C:/HERE/NOW; D:/THERE/THEN', });
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
.
# on Win32 only my $template = Template->new({ INCLUDE_PATH => 'C:/Foo:C:/Bar' });
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.
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.
my $template = Template->new({ ABSOLUTE => 1, }); # this is why it's disabled by default [% INSERT /etc/passwd %]
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:
C:/Foo/Bar
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.
my $template = Template->new({ RELATIVE => 1, }); [% INCLUDE ../logs/error.log %]
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
.
my $template = Template->new({ DEFAULT => 'notfound.html', });
If a non-existent 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.
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 the Template::Document manpage
objects.
my $template = Template->new({ BLOCKS => { header => 'The Header. [% title %]', footer => sub { return $some_output_text }, another => Template::Document->new({ ... }), }, });
The VIEWS option can be used to define one or more the Template::View manpage objects. They can be specified as a reference to a hash array or list reference.
my $template = Template->new({ VIEWS => { my_view => { prefix => 'my_templates/' }, }, });
Be aware of the fact that Perl's hash array are unordered, so if you want to specify multiple views of which one or more are based on other views, then you should use a list reference to preserve the order of definition.
my $template = Template->new({ VIEWS => [ bottom => { prefix => 'bottom/' }, middle => { prefix => 'middle/', base => 'bottom' }, top => { prefix => 'top/', base => 'middle' }, ], });
The AUTO_RESET
option is set by default and causes the local BLOCKS
cache for the the Template::Context manpage object to be reset on each call to the
Template process() method. This ensures that any BLOCK
s
defined within a template will only persist until that template is finished
processing. This prevents BLOCK
s defined in one processing request from
interfering with other independent requests subsequently processed by the same
context object.
The BLOCKS
item may be used to specify a default set of block definitions
for the the Template::Context manpage 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 the Template::Context manpage
reset() method is called.
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.
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.
my $template = Template->new({ VARIABLES => { title => 'A Demo Page', author => 'Joe Random Hacker', version => 3.14, }, };
or
my $template = Template->new({ PRE_DEFINE => { title => 'A Demo Page', author => 'Joe Random Hacker', version => 3.14, }, };
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.
my $template = Template->new({ CONSTANTS => { title => 'A Demo Page', author => 'Joe Random Hacker', version => 3.14, }, };
Constant variables are accessed via the constants
namespace by
default.
[% constants.title %]
The CONSTANTS_NAMESPACE
option can be set to specify an alternate
namespace.
my $template = Template->new({ CONSTANTS => { title => 'A Demo Page', # ...etc... }, CONSTANTS_NAMESPACE => 'const', };
In this case the constants would then be accessed as:
[% const.title %]
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.
Under the hood, the Template module converts a constructor configuration such as:
my $template = Template->new({ CONSTANTS => { title => 'A Demo Page', # ...etc... }, CONSTANTS_NAMESPACE => 'const', };
into one like:
my $template = Template->new({ NAMESPACE => { const => Template:::Namespace::Constants->new({ title => 'A Demo Page', # ...etc... }), }, };
You can use this mechanism to define multiple constant namespaces, or to install custom handlers of your own.
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( ... ), }, };
Now you have two constant namespaces, for example:
[% site.title %] [% author.name %]
as well as your own custom namespace handler installed for the 'voodoo' namespace.
[% voodoo.magic %]
See the Template::Namespace::Constants manpage for an example of what a namespace handler looks like on the inside.
The following options are used to specify any additional templates that should be processed before, after, around or instead of the template passed as the first argument to the Template process() method. These options can be perform various useful tasks such as adding standard headers or footers to all pages, wrapping page output in other templates, pre-defining variables or performing initialisation or cleanup tasks, automatically generating page summary information, navigation elements, and so on.
The task of processing the template is delegated internally to the
the Template::Service manpage module which, unsurprisingly, also has a
process() method. Any templates defined by the
PRE_PROCESS
option are processed first and any output generated is added to
the output buffer. Then the main template is processed, or if one or more
PROCESS
templates are defined then they are instead processed in turn. In this
case, one of the PROCESS
templates is responsible for processing the main
template, by a directive such as:
[% PROCESS $template %]
The output of processing the main template or the PROCESS
template(s)
is then wrapped in any WRAPPER
templates, if defined. WRAPPER
templates don't need to worry about explicitly processing the template
because it will have been done for them already. Instead WRAPPER
templates access the content they are wrapping via the content
variable.
wrapper before [% content %] wrapper after
This output generated from processing the main template, and/or any
PROCESS
or WRAPPER
templates is added to the output buffer. Finally,
any POST_PROCESS
templates are processed and their output is also
added to the output buffer which is then returned.
If the main template throws an exception during processing then any relevant
template(s)
defined via the ERROR
option will be processed instead. If
defined and successfully processed, the output from the error template will be
added to the output buffer in place of the template that generated the error
and processing will continue, applying any WRAPPER
and POST_PROCESS
templates. If no relevant ERROR
option is defined, or if the error occurs
in one of the PRE_PROCESS
, WRAPPER
or POST_PROCESS
templates, then
the process will terminate immediately and the error will be returned.
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.
my $template = Template->new({ PRE_PROCESS => 'header', POST_PROCESS => 'footer', };
Multiple templates may be specified as a reference to a list. Each is processed in the order defined.
my $template = Template->new({ PRE_PROCESS => [ 'config', 'header' ], POST_PROCESS => 'footer', };
Alternately, multiple template may be specified as a single string,
delimited by ':
'. This delimiter string can be changed via the
DELIMITER
option.
my $template = Template->new({ PRE_PROCESS => 'config:header', POST_PROCESS => 'footer', };
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.
config:
[% # set some site-wide variables bgcolor = '#ffffff' version = 2.718 %]
header:
[% DEFAULT title = 'My Funky Web Site' %] <html> <head> <title>[% title %]</title> </head> <body bgcolor="[% bgcolor %]">
footer:
<hr> Version [% version %] </body> </html>
The the Template::Document manpage 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.
$template->process('mydoc.html', $vars);
mydoc.html:
[% META title = 'My Document Title' %] blah blah blah ...
header:
<html> <head> <title>[% template.title %]</title> </head> <body bgcolor="[% bgcolor %]">
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.
my $template = Template->new({ PROCESS => 'content', }; # processes 'content' instead of 'foo.html' $template->process('foo.html');
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.
content:
<html> <head> <title>[% template.title %]</title> </head> <body> <!-- begin content --> [% PROCESS $template %] <!-- end content --> <hr> © Copyright [% template.copyright %] </body> </html>
foo.html:
[% META title = 'The Foo Page' author = 'Fred Foo' copyright = '2000 Fred Foo' %] <h1>[% template.title %]</h1> Welcome to the Foo Page, blah blah blah
output:
<html> <head> <title>The Foo Page</title> </head> <body> <!-- begin content --> <h1>The Foo Page</h1> Welcome to the Foo Page, blah blah blah <!-- end content --> <hr> © Copyright 2000 Fred Foo </body> </html>
The WRAPPER
option can be used to specify one or more templates which
should be used to wrap around the output of the main page template.
The main template is processed first (or any PROCESS
template(s))
and
the output generated is then passed as the content
variable to the
WRAPPER
template(s)
as they are processed.
my $template = Template->new({ WRAPPER => 'wrapper', }; # process 'foo' then wrap in 'wrapper' $template->process('foo', { message => 'Hello World!' });
wrapper:
<wrapper> [% content %] </wrapper>
foo:
This is the foo file! Message: [% message %]
The output generated from this example is:
<wrapper> This is the foo file! Message: Hello World! </wrapper>
You can specify more than one WRAPPER
template by setting the value to
be a reference to a list of templates. The WRAPPER
templates will be
processed in reverse order with the output of each being passed to the
next (or previous, depending on how you look at it) as the 'content'
variable. It sounds complicated, but the end result is that it just
``Does The Right Thing'' to make wrapper templates nest in the order you
specify.
my $template = Template->new({ WRAPPER => [ 'outer', 'inner' ], }; # process 'foo' then wrap in 'inner', then in 'outer' $template->process('foo', { message => 'Hello World!' });
outer:
<outer> [% content %] </outer>
inner:
<inner> [% content %] </inner>
The output generated is then:
<outer> <inner> This is the foo file! Message: Hello World! </inner> </outer>
One side-effect of the ``inside-out'' processing of the WRAPPER
configuration item (and also the WRAPPER
directive) is that any
variables set in the template being wrapped will be visible to the
template doing the wrapping, but not the other way around.
You can use this to good effect in allowing page templates to set pre-defined values which are then used in the wrapper templates. For example, our main page template 'foo' might look like this:
foo:
[% page = { title = 'Foo Page' subtitle = 'Everything There is to Know About Foo' author = 'Frank Oliver Octagon' } %] <p> Welcome to the page that tells you everything about foo blah blah blah... </p>
The foo
template is processed before the wrapper template meaning
that the page
data structure will be defined for use in the wrapper
template.
wrapper:
<html> <head> <title>[% page.title %]</title> </head> <body> <h1>[% page.title %]</h1> <h2>[% page.subtitle %]</h1> <h3>by [% page.author %]</h3> [% content %] </body> </html>
It achieves the same effect as defining META
items which are then
accessed via the template
variable (which you are still free to
use within WRAPPER
templates), but gives you more flexibility in
the type and complexity of data that you can define.
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.
If specified as a single value then that template will be processed for all uncaught exceptions.
my $template = Template->new({ ERROR => 'error.html' });
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.
my $template = Template->new({ ERRORS => { user => 'user/index.html', dbi => 'error/database', default => 'error/default', }, });
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.
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. user.passwd
is parsed as 'user'.'passwd'
).
my $template = Template->new({ ERROR => { 'user.login' => 'user/login.html', 'user.passwd' => 'user/badpasswd.html', 'user' => 'user/index.html', 'default' => 'error/default', }, });
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.
Exceptions can be raised in a template using the THROW
directive,
[% THROW user.login 'no user id: please login' %]
or by calling the throw() method on the current the Template::Context manpage object,
$context->throw('user.passwd', 'Incorrect Password'); $context->throw('Incorrect Password'); # type 'undef'
or from Perl code by calling die()
with a the Template::Exception manpage object,
die (Template::Exception->new('user.denied', 'Invalid User ID'));
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.
die "I'm sorry Dave, I can't do that";
Note that the 'undef
' we're talking about here is a literal string
rather than Perl's undef
used to represent undefined values.
This flag is used to indicate if PERL
and/or RAWPERL
blocks should be
evaluated. It is disabled by default 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.
When using compiled templates (see
Caching and Compiling Options),
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.
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
always throws a 'perl
' exception with the message 'EVAL_PERL not
set
' whenever the compiled template code is run.
Thus, you must have EVAL_PERL
set if you want your compiled templates
to include PERL
and RAWPERL
blocks.
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.
Regular PERL
blocks are a little more cautious, however. If the
EVAL_PERL
flag isn't set for the current 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
'.
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.
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 the IO::Handle manpage) 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.
example 1 (file name):
my $template = Template->new({ OUTPUT => "/tmp/foo", });
example 2 (text string):
my $output = ''; my $template = Template->new({ OUTPUT => \$output, });
example 3 (file handle):
open (TOUT, "> $file") || die "$file: $!\n"; my $template = Template->new({ OUTPUT => \*TOUT, });
example 4 (subroutine):
sub output { my $out = shift; print "OUTPUT: $out" } my $template = Template->new({ OUTPUT => \&output, });
example 5 (array reference):
my $template = Template->new({ OUTPUT => \@output, })
example 6 (Apache/mod_perl handler):
sub handler { my $r = shift; my $t = Template->new({ OUTPUT => $r, }); ... }
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.
$t->process($file, $vars, "/tmp/foo"); $t->process($file, $vars, \$output); $t->process($file, $vars, \*MYGLOB); $t->process($file, $vars, \@output); $t->process($file, $vars, $r); # Apache::Request ...
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.
my $template = Template->new({ INCLUDE_PATH => "/tmp/src", OUTPUT_PATH => "/tmp/dest", }); my $vars = { ... }; foreach my $file ('foo.html', 'bar.html') { $template->process($file, $vars, $file) || die $template->error(); }
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.
By default the Template Toolkit will silently ignore the use of undefined variables (a bad design decision that I regret).
When the STRICT
option is set, the use of any undefined variables or
values will cause an exception to be throw. The exception will have a
type
of var.undefined
and a message of the form
``undefined variable: xxx''.
my $template = Template->new( STRICT => 1 );
The DEBUG
option can be used to enable debugging within the various
different modules that comprise the Template Toolkit. The
the Template::Constants manpage module defines a set of
DEBUG_XXXX
constants which can be combined using the logical OR
operator, '|
'.
use Template::Constants qw( :debug ); my $template = Template->new({ DEBUG => DEBUG_PARSER | DEBUG_PROVIDER, });
For convenience, you can also provide a string containing a list of lower case debug options, separated by any non-word characters.
my $template = Template->new({ DEBUG => 'parser, provider', });
The following DEBUG_XXXX
flags can be used:
undef
' error
whenever it encounters an undefined variable value.
DEBUG_FORMAT
configuration item, or a
simple default format if unspecified.
For example, the following template fragment:
Hello World
would generate this output:
## input text line 1 : ## Hello ## input text line 2 : World ## World
The DEBUG_FORMAT
option can be used to specify a format string for the
debugging messages generated via the DEBUG_DIRS
option described
above. Any occurrences of $file
, $line
or $text
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.
my $template = Template->new({ DEBUG => 'dirs', DEBUG_FORMAT => '<!-- $file line $line : [% $text %] -->', });
The following template fragment:
[% foo = 'World' %] Hello [% foo %]
would then generate this output:
<!-- input text line 2 : [% foo = 'World' %] --> Hello <!-- input text line 3 : [% foo %] -->World
The DEBUG directive can also be used to set a debug format within a template.
[% DEBUG format '<!-- $file line $line : [% $text %] -->' %]
The the Template::Provider manpage 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.
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.
The CACHE_SIZE
can be set to 0
to disable caching altogether.
my $template = Template->new({ CACHE_SIZE => 64, # only cache 64 compiled templates });
my $template = Template->new({ CACHE_SIZE => 0, # don't cache any compiled templates });
As well as caching templates as they are found, the the Template::Provider manpage
also implements negative caching to keep track of templates that are
not found. This allows the provider to quickly decline a request
for a template that it has previously failed to locate, saving the effort
of going to look for it again. This is useful when an INCLUDE_PATH
includes
multiple providers, ensuring that the request is passed down through the
providers as quickly as possible.
This value can be set to control how long the the Template::Provider manpage will keep a template cached in memory before checking to see if the source template has changed.
my $provider = Template::Provider->new({ STAT_TTL => 60, # one minute });
The default value is 1 (second). You'll probably want to set this to a higher value if you're running the Template Toolkit inside a persistent web server application (e.g. mod_perl). For example, set it to 60 and the provider will only look for changes to templates once a minute at most. However, during development (or any time you're making frequent changes to templates) you'll probably want to keep it set to a low value so that you don't have to wait for the provider to notice that your templates have changed.
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.
my $template = Template->new({ COMPILE_EXT => '.ttc', });
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.
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.
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.
The COMPILE_DIR
option is used to specify an alternate directory root
under which compiled template files should be saved.
my $template = Template->new({ COMPILE_DIR => '/tmp/ttc', });
The COMPILE_EXT
option may also be specified to have a consistent file
extension added to these files.
my $template1 = Template->new({ COMPILE_DIR => '/tmp/ttc', COMPILE_EXT => '.ttc1', });
my $template2 = Template->new({ COMPILE_DIR => '/tmp/ttc', COMPILE_EXT => '.ttc2', });
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.
Each directory in the INCLUDE_PATH
is replicated in full beneath the
COMPILE_DIR
directory. This example:
my $template = Template->new({ COMPILE_DIR => '/tmp/ttc', INCLUDE_PATH => '/home/abw/templates:/usr/share/templates', });
would create the following directory structure:
/tmp/ttc/home/abw/templates/ /tmp/ttc/usr/share/templates/
Files loaded from different INCLUDE_PATH
directories will have their
compiled forms save in the relevant COMPILE_DIR
directory.
On Win32 platforms a filename may by prefixed by a drive letter and colon. e.g.
C:/My Templates/header
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:
# Win32 only my $template = Template->new({ DELIMITER => ';', COMPILE_DIR => 'C:/TT2/Cache', INCLUDE_PATH => 'C:/TT2/Templates;D:/My Templates', });
This would create the following cache directories:
C:/TT2/Cache/C/TT2/Templates C:/TT2/Cache/D/My Templates
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
, format
, cgi
, etc.) which map to
their corresponding Template::Plugin::*
counterparts. These can be
redefined by values in the PLUGINS
hash.
my $template = Template->new({ PLUGINS => { cgi => 'MyOrg::Template::Plugin::CGI', foo => 'MyOrg::Template::Plugin::Foo', bar => 'MyOrg::Template::Plugin::Bar', }, });
The recommended convention is to specify these plugin names in lower case. The Template Toolkit first looks for an exact case-sensitive match and then tries the lower case conversion of the name specified.
[% USE Foo %] # look for 'Foo' then 'foo'
If you define all your PLUGINS
with lower case names then they will be
located regardless of how the user specifies the name in the USE
directive. If, on the other hand, you define your PLUGINS
with upper
or mixed case names then the name specified in the USE
directive must
match the case exactly.
The USE
directive is used to create plugin objects and does so by calling
the plugin() method on the current
the Template::Context manpage 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.
If the plugin name is not defined in the PLUGINS
hash then the
PLUGIN_BASE
and/or LOAD_PERL
options come into effect.
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.
The PLUGIN_BASE
can be specified as a reference to an array of module
namespaces, or as a single value which is automatically converted to a
list. The default PLUGIN_BASE
value (Template::Plugin
) is then added
to the end of this list.
example 1:
my $template = Template->new({ PLUGIN_BASE => 'MyOrg::Template::Plugin', }); [% USE Foo %] # => MyOrg::Template::Plugin::Foo or Template::Plugin::Foo
example 2:
my $template = Template->new({ PLUGIN_BASE => [ 'MyOrg::Template::Plugin', 'YourOrg::Template::Plugin' ], });
template:
[% USE Foo %] # => MyOrg::Template::Plugin::Foo or YourOrg::Template::Plugin::Foo or Template::Plugin::Foo
If you don't want the default Template::Plugin
namespace added to the
end of the PLUGIN_BASE
, then set the $Template::Plugins::PLUGIN_BASE
variable to a false value before calling the new() Template#new()
constructor method. This is shown in the example below where the
Foo
plugin is located as My::Plugin::Foo
or Your::Plugin::Foo
but not
as Template::Plugin::Foo
.
example 3:
use Template::Plugins; $Template::Plugins::PLUGIN_BASE = ''; my $template = Template->new({ PLUGIN_BASE => [ 'My::Plugin', 'Your::Plugin' ], });
template:
[% USE Foo %] # => My::Plugin::Foo or Your::Plugin::Foo
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
the Template::Plugin manpage or some other such namespace) to be loaded and used
as plugins.
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.
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 the Template::Plugin manpage 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.
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.
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.
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.
$template = Template->new({ FILTERS => { 'sfilt1' => \&static_filter, # static 'sfilt2' => [ \&static_filter, 0 ], # same as above 'dfilt1' => [ \&dyanamic_filter_factory, 1 ], }, });
Additional filters can be specified at any time by calling the define_filter() method on the current the Template::Context manpage object. The method accepts a filter name, a reference to a filter subroutine and an optional flag to indicate if the filter is dynamic.
my $context = $template->context(); $context->define_filter('new_html', \&new_html); $context->define_filter('new_repeat', \&new_repeat, 1);
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.
sub static_filter { my $text = shift; # do something to modify $text... return $text; }
The following template fragment:
[% FILTER sfilt1 %] Blah blah blah. [% END %]
is approximately equivalent to:
&static_filter("\nBlah blah blah.\n");
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
the Template::Context manpage 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.
sub dynamic_filter_factory { my ($context, @args) = @_; return sub { my $text = shift; # do something to modify $text... return $text; } }
The following template fragment:
[% FILTER dfilt1(123, 456) %] Blah blah blah [% END %]
is approximately equivalent to:
my $filter = &dynamic_filter_factory($context, 123, 456); &$filter("\nBlah blah blah.\n");
See the FILTER
directive for further examples.
The LOAD_TEMPLATES
option can be used to provide a reference to a list
of the Template::Provider manpage objects or sub-classes thereof which will take
responsibility for loading and compiling templates.
my $template = Template->new({ LOAD_TEMPLATES => [ MyOrg::Template::Provider->new({ ... }), Template::Provider->new({ ... }), ], });
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 the Template::Context manpage 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.
If LOAD_TEMPLATES
is undefined, a single default provider will be
instantiated using the current configuration parameters. For example, the
the Template::Provider manpage INCLUDE_PATH
option can be specified in the Template
configuration and will be correctly passed to the provider's constructor
method.
my $template = Template->new({ INCLUDE_PATH => '/here:/there', });
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
the Template::Context manpage plugin() method queries
each provider in turn in a ``Chain of Responsibility'' as per the
template() and
filter() methods.
my $template = Template->new({ LOAD_PLUGINS => [ MyOrg::Template::Plugins->new({ ... }), Template::Plugins->new({ ... }), ], });
By default, a single the Template::Plugins manpage object is created using the current configuration hash. Configuration items destined for the the Template::Plugins manpage constructor may be added to the Template constructor.
my $template = Template->new({ PLUGIN_BASE => 'MyOrg::Template::Plugins', LOAD_PERL => 1, });
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
the Template::Context manpage filter() method queries
each provider in turn in a ``Chain of Responsibility'' as per the
template() and
plugin() methods.
my $template = Template->new({ LOAD_FILTERS => [ MyTemplate::Filters->new(), Template::Filters->new(), ], });
By default, a single the Template::Filters manpage object is created for the
LOAD_FILTERS
list.
The TOLERANT
flag is used by the various Template Toolkit provider modules
(the Template::Provider manpage, the Template::Plugins manpage, the Template::Filters manpage) 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.
A reference to a the Template::Service manpage object, or sub-class thereof, to which the Template module should delegate. If unspecified, a the Template::Service manpage object is automatically created using the current configuration hash.
my $template = Template->new({ SERVICE => MyOrg::Template::Service->new({ ... }), });
A reference to a the Template::Context manpage object which is used to define a
specific environment in which template are processed. A the Template::Context manpage
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
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.
my $template = Template->new({ CONTEXT => MyOrg::Template::Context->new({ ... }), });
A reference to a the Template::Stash manpage object or sub-class which will take responsibility for managing template variables.
my $stash = MyOrg::Template::Stash->new({ ... }); my $template = Template->new({ STASH => $stash, });
If unspecified, a default stash object is created using the VARIABLES
configuration item to initialise the stash variables.
my $template = Template->new({ VARIABLES => { id => 'abw', name => 'Andy Wardley', }, };
The the Template::Parser manpage 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
the Template::Provider manpage whenever a template is loaded and requires
compilation. The PARSER
option can be used to provide a reference to
an alternate parser object.
my $template = Template->new({ PARSER => MyOrg::Template::Parser->new({ ... }), });
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.
Source templates are compiled to Perl code by the the Template::Parser manpage using the the Template::Grammar manpage (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).
The the Template::Grammar manpage 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.
By default, an instance of the default the Template::Grammar manpage will be
created and used automatically if a GRAMMAR
item isn't specified.
use MyOrg::Template::Grammar; my $template = Template->new({ GRAMMAR = MyOrg::Template::Grammar->new(); });
Template::Manual::Config - Configuration options |