Template::Manual::Config
Template::Manual::ConUser3Contributed Perl DocumenTemplate::Manual::Config(3)
NAME
Template::Manual::Config - Configuration options
Template Style and Parsing Options
START_TAG, END_TAG
The "START_TAG" and "END_TAG" options are used to specify character
sequences or regular expressions that mark the start and end of a tem-
plate 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 repre-
sent 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 <+ +> %]
TAG_STYLE
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 -->
PRE_CHOMP, POST_CHOMP
Anything outside a directive tag is considered plain text and is gen-
erally 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_COL-
LAPSE" and "CHOMP_GREEDY" constants in the Template::Constants module.
"CHOMP_ALL" is also defined as an alias for "CHOMP_ONE" to provide
backwards compatability 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 direc-
tives 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 ~
TRIM
The "TRIM" option can be set to have any leading and trailing whites-
pace 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.
INTERPOLATE
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 tem-
plates 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".
ANYCASE
By default, directive keywords should be expressed in UPPER CASE. The
"ANYCASE" option can be set to allow directive keywords to be speci-
fied 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 vari-
able 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
Template Files and Blocks
INCLUDE_PATH
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 subrou-
tine 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;
DELIMITER
Used to provide an alternative delimiter character sequence for sepa-
rating 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, split-
ting 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 explic-
itly set the "DELIMITER" character to something else (e.g. ’";"’)
rather than rely on this subtle magic.
ABSOLUTE
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 path-
names is tweaked slightly to also detect filenames that start with a
driver letter and colon, such as:
C:/Foo/Bar
RELATIVE
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 %]
DEFAULT
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-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 han-
dle or text string.
BLOCKS
The "BLOCKS" option can be used to pre-define a default set of tem-
plate blocks. These should be specified as a reference to a hash
array mapping template names to template text, subroutines or Tem-
plate::Document objects.
my $template = Template->new({
BLOCKS => {
header => ’The Header. [% title %]’,
footer => sub { return $some_output_text },
another => Template::Document->new({ ... }),
},
});
AUTO_RESET
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 "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 defi-
nitions for the Template::Context object. Subsequent "BLOCK" defini-
tions in templates will over-ride these but they will be reinstated on
each reset if "AUTO_RESET" is enabled (default), or if the Tem-
plate::Context reset() method is called.
RECURSION
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.
Template Variables
VARIABLES
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,
},
};
CONSTANTS
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_NAMESPACE
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 %]
NAMESPACE
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 configura-
tion 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 Template::Namespace::Constants for an example of what a namespace
handler looks like on the inside.
Template Processing Options
The following options are used to specify any additional templates
that should be processed before, after, around or instead of the tem-
plate passed as the first argument to the Template process() method.
These options can be perform various useful tasks such as adding stan-
dard 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, nav-
igation elements, and so on.
The task of processing the template is delegated internally to the
Template::Service module which, unsurprisingly, also has a process()
method. Any templates defined by the "PRE_PROCESS" option are pro-
cessed first and any output generated is added to the output buffer.
Then the main template is processed, or if one or more "PROCESS" tem-
plates 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" tem-
plate(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 "con-
tent" 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 tem-
plate 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.
PRE_PROCESS, POST_PROCESS
These values may be set to contain the name(s) of template files (rel-
ative to "INCLUDE_PATH") which should be processed immediately before
and/or after each template. These do not get added to templates pro-
cessed 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 Template::Document object representing the main template being
processed is available within "PRE_PROCESS" and "POST_PROCESS" tem-
plates 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 %]">
PROCESS
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>
WRAPPER
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 tem-
plate. The main template is processed first (or any "PROCESS" tem-
plate(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" con-
figuration item (and also the "WRAPPER" directive) is that any vari-
ables set in the template being wrapped will be visible to the tem-
plate 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.
ERROR
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 appropri-
ate 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 tem-
plate. 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 Template::Context
object,
$context->throw(’user.passwd’, ’Incorrect Password’);
$context->throw(’Incorrect Password’); # type ’undef’
or from Perl code by calling "die()" with a Template::Exception
object,
die (Template::Exception->new(’user.denied’, ’Invalid User ID’));
or by simply calling die() with an error string. This is automagi-
cally 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.
Template Runtime Options
EVAL_PERL
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 tem-
plates to include "PERL" and "RAWPERL" blocks.
At some point in the future, using a different invocation of the Tem-
plate 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 pro-
cessed. This will happen regardless of the runtime "EVAL_PERL" sta-
tus.
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 option-
ally 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 tem-
plates, 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.
OUTPUT
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 refer-
ence 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 parame-
ter 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
...
OUTPUT_PATH
The "OUTPUT_PATH" allows a directory to be specified into which output
files should be written. An output file can be specified by the "OUT-
PUT" 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.
DEBUG
The "DEBUG" option can be used to enable debugging within the various
different modules that comprise the Template Toolkit. The Tem-
plate::Constants 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:
DEBUG_SERVICE
Enables general debugging messages for the Template::Service mod-
ule.
DEBUG_CONTEXT
Enables general debugging messages for the Template::Context mod-
ule.
DEBUG_PROVIDER
Enables general debugging messages for the Template::Provider mod-
ule.
DEBUG_PLUGINS
Enables general debugging messages for the Template::Plugins mod-
ule.
DEBUG_FILTERS
Enables general debugging messages for the Template::Filters mod-
ule.
DEBUG_PARSER
This flag causes the Template::Parser to generate debugging mes-
sages that show the Perl code generated by parsing and compiling
each template.
DEBUG_UNDEF
This option causes the Template Toolkit to throw an ’"undef"’
error whenever it encounters an undefined variable value.
DEBUG_DIRS
This option causes the Template Toolkit to generate comments indi-
cating the source file, line and original text of each directive
in the template. These comments are embedded in the template out-
put using the format defined in the "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
DEBUG_ALL
Enables all debugging messages.
DEBUG_CALLER
This option causes all debug messages that aren’t newline termi-
nated to have the file name and line number of the caller appended
to them.
DEBUG_FORMAT
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 occurances 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 %] -->’ %]
Caching and Compiling Options
CACHE_SIZE
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.
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 Template::Provider
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.
STAT_TTL
This value can be set to control how long the Template::Provider 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 persis-
tent 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 fre-
quent 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.
COMPILE_EXT
From version 2 onwards, the Template Toolkit has the ability to com-
pile 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 unde-
fined by default and no attempt will be made to read or write any com-
piled 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 writ-
ten 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 Tem-
plate Toolkit will automatically reload and reuse compiled files when
it finds them on disk. If the corresponding source file has been mod-
ified 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.
COMPILE_DIR
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 gener-
ated. 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
Plugins and Filters
PLUGINS
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 stan-
dard 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" direc-
tive 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 Template::Context object.
If the plugin name is defined in the "PLUGINS" hash then the corre-
sponding 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 "PLU-
GIN_BASE" and/or "LOAD_PERL" options come into effect.
PLUGIN_BASE
If a plugin is not defined in the "PLUGINS" hash then the "PLU-
GIN_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 mod-
ule 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::PLU-
GIN_BASE variable to a false value before calling the new() Tem-
plate#new() constructor method. This is shown in the example below
where the "Foo" plugin is located as "My::Plugin::Foo" or "Your::Plu-
gin::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
LOAD_PERL
If a plugin cannot be loaded using the "PLUGINS" or "PLUGIN_BASE"
approaches then the provider can make a final attempt to load the mod-
ule without prepending any prefix to the module path. This allows
regular Perl modules (i.e. those that don’t reside in the Tem-
plate::Plugin 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 "PLU-
GIN_BASE" components.
Plugins loaded using the "PLUGINS" or "PLUGIN_BASE" receive a refer-
ence to the current context object as the first argument to the new()
constructor. Modules loaded using "LOAD_PERL" are assumed to not con-
form 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.
If a particular Perl module does not conform to the common, but not
unilateral, "new()" constructor convention then a simple plugin wrap-
per can be written to interface to it.
FILTERS
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 corre-
sponding 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 soli-
tary 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 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.
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 stati-
cally. The subroutine reference is simply returned when that particu-
lar filter is requested. The subroutine is called to filter the out-
put 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 imple-
mented 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::Con-
text object is passed as the first parameter, followed by any addi-
tional 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.
Customisation and Extension
LOAD_TEMPLATES
The "LOAD_TEMPLATES" 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.
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 rela-
tive 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_TEM-
PLATES" 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" defi-
nitions 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 Template::Provider "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’,
});
LOAD_PLUGINS
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 Tem-
plate::Context 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 Template::Plugins object is created using the
current configuration hash. Configuration items destined for the Tem-
plate::Plugins constructor may be added to the Template constructor.
my $template = Template->new({
PLUGIN_BASE => ’MyOrg::Template::Plugins’,
LOAD_PERL => 1,
});
LOAD_FILTERS
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::Con-
text 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 Template::Filters object is created for the
"LOAD_FILTERS" list.
TOLERANT
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 excep-
tion raised.
When the "TOLERANT" flag is set to any true values, errors will be
silently ignored and the provider will instead return "STA-
TUS_DECLINED". This allows a subsequent provider to take responsibil-
ity for providing the resource, rather than failing the request out-
right. 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.
SERVICE
A reference to a Template::Service object, or sub-class thereof, to
which the Template module should delegate. If unspecified, a Tem-
plate::Service object is automatically created using the current con-
figuration hash.
my $template = Template->new({
SERVICE => MyOrg::Template::Service->new({ ... }),
});
CONTEXT
A reference to a Template::Context object which is used to define a
specific environment in which template are processed. A Template::Con-
text 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 tem-
plate (include() and process() methods, respectively), to "USE" a plu-
gin (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({ ... }),
});
STASH
A reference to a Template::Stash 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 "VARI-
ABLES" configuration item to initialise the stash variables.
my $template = Template->new({
VARIABLES => {
id => ’abw’,
name => ’Andy Wardley’,
},
};
PARSER
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 Tem-
plate::Provider whenever a template is loaded and requires compila-
tion. The "PARSER" option can be used to provide a reference to an
alternate parser object.
my $template = Template->new({
PARSER => MyOrg::Template::Parser->new({ ... }),
});
GRAMMAR
The "GRAMMAR" configuration item can be used to specify an alternate
grammar for the parser. This allows a modified or entirely new tem-
plate language to be constructed and used by the Template Toolkit.
Source templates are compiled to Perl code by the Template::Parser
using the Template::Grammar (by default) to define the language struc-
ture and semantics. Compiled templates are thus inherently "compati-
ble" 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 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.
By default, an instance of the default Template::Grammar will be cre-
ated and used automatically if a "GRAMMAR" item isn’t specified.
use MyOrg::Template::Grammar;
my $template = Template->new({
GRAMMAR = MyOrg::Template::Grammar->new();
});
perl v5.8.8 2007-06-05 Template::Manual::Config(3)
