[% myorg.name %]
# INTERPOLATE => 1
$myorg.name
# explicit scoping with { }
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 C[% text | html %]
[% END %]
[% PROCESS frag %]
[% PROCESS frag text="foo is the new bar" %]
when processed as Fs wrapped in C tags,
but when processed as F, will output only the C
from the
F C.
=head1 Template Variables
=head2 VARIABLES
The C option (or C - 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 C 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,
},
};
=head2 CONSTANTS
The C 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,
},
};
=head2 CONSTANT_NAMESPACE
Constant variables are accessed via the C namespace by
default.
[% constants.title %]
The C 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 %]
=head2 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 L 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 L
for an example of what a namespace handler looks like on the inside.
=head1 Template Processing Options
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 L L 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
L module which, unsurprisingly, also has a
L method. Any templates defined by the
C 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
C templates are defined then they are instead processed in turn. In this
case, one of the C templates is responsible for processing the main
template, by a directive such as:
[% PROCESS $template %]
The output of processing the main template or the C template(s)
is then wrapped in any C templates, if defined. C
templates don't need to worry about explicitly processing the template
because it will have been done for them already. Instead C
templates access the content they are wrapping via the C
variable.
wrapper before
[% content %]
wrapper after
This output generated from processing the main template, and/or any
C or C templates is added to the output buffer. Finally,
any C 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 C 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 C and C
templates. If no relevant C option is defined, or if the error occurs
in one of the C, C or C templates, then
the process will terminate immediately and the error will be returned.
=head2 PRE_PROCESS, POST_PROCESS
These values may be set to contain the name(s) of template files
(relative to C) 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 C,
C, C 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 'C<:>'. This delimiter string can be changed via the
C option.
my $template = Template->new({
PRE_PROCESS => 'config:header',
POST_PROCESS => 'footer',
};
The C and C 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' %]
[% title %]
footer:
Version [% version %] The L object representing the main template being processed
is available within C and C templates as the C
variable. Metadata items defined via the C directive may be accessed
accordingly.
$template->process('mydoc.html', $vars);
mydoc.html:
[% META title = 'My Document Title' %]
blah blah blah
...
header:
[% template.title %]
=head2 PROCESS
The C option may be set to contain the name(s) of template files
(relative to C) which should be processed instead of the main
template passed to the L L method.
This can be used to apply consistent wrappers around all templates, similar to
the use of C and C 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 C
variable. Metadata items can be inspected and the template can be
processed by specifying it as a variable reference (i.e. prefixed by
C<$>) to an C, C or C directive.
content:
[% template.title %]
[% PROCESS $template %]
© Copyright [% template.copyright %] foo.html: [% META title = 'The Foo Page' author = 'Fred Foo' copyright = '2000 Fred Foo' %]The Foo Page
© Copyright 2000 Fred Foo =head2 WRAPPER The C 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 C template(s)) and
the output generated is then passed as the C variable to the
C 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:
[% content %]
foo:
This is the foo file!
Message: [% message %]
The output generated from this example is:
This is the foo file!
Message: Hello World!
You can specify more than one C template by setting the value to
be a reference to a list of templates. The C 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:
[% content %]
inner:
[% content %]
The output generated is then:
This is the foo file!
Message: Hello World!
One side-effect of the "inside-out" processing of the C
configuration item (and also the C 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'
}
%]
template is processed before the wrapper template meaning
that the C data structure will be defined for use in the wrapper
template.
wrapper:
[% page.title %]
[% page.subtitle %]
Version [% version %] The L
© Copyright [% template.copyright %] foo.html: [% META title = 'The Foo Page' author = 'Fred Foo' copyright = '2000 Fred Foo' %]
[% template.title %]
Welcome to the Foo Page, blah blah blah output:The Foo Page
Welcome to the Foo Page, blah blah blah© Copyright 2000 Fred Foo =head2 WRAPPER The C
Welcome to the page that tells you everything about foo blah blah blah...
The C