NAME
Apache::Template - Apache/mod_perl interface to the Template Toolkit
SYNOPSIS
# add the following to your httpd.conf
PerlModule Apache::Template
# set various configuration options, e.g.
TT2Trim On
TT2PostChomp On
TT2EvalPerl On
TT2IncludePath /usr/local/tt2/templates
TT2IncludePath /home/abw/tt2/lib
TT2PreProcess config header
TT2PostProcess footer
TT2Error error
# now define Apache::Template as a PerlHandler, e.g.
SetHandler perl-script
PerlHandler Apache::Template
SetHandler perl-script
PerlHandler Apache::Template
DESCRIPTION
The Apache::Template module provides a simple interface to the Template
Toolkit from Apache/mod_perl. The Template Toolkit is a fast, powerful
and extensible template processing system written in Perl. It implements
a general purpose template language which allows you to clearly separate
application logic, data and presentation elements. It boasts numerous
features to facilitate in the generation of web content both online and
offline in "batch mode".
This documentation describes the Apache::Template module, concerning
itself primarily with the Apache/mod_perl configuration options (e.g.
the httpd.conf side of things) and not going into any great depth about
the Template Toolkit itself. The Template Toolkit includes copious
documentation which already covers these things in great detail. See
Template and Template::Manual for further information.
CONFIGURATION
Most of the Apache::Template configuration directives relate directly to
their Template Toolkit counterparts, differing only in having a 'TT2'
prefix, mixed capitalisation and lack of underscores to space individual
words. This is to keep Apache::Template configuration directives in
keeping with the preferred Apache/mod_perl style.
e.g.
Apache::Template => Template Toolkit
--------------------------------------
TT2Trim TRIM
TT2IncludePath INCLUDE_PATH
TT2PostProcess POST_PROCESS
...etc...
In some cases, the configuration directives are named or behave slightly
differently to optimise for the Apache/mod_perl environment or domain
specific features. For example, the TT2Tags configuration directive can
be used to set TAG_STYLE and/or START_TAG and END_TAG and as such, is
more akin to the Template Toolkit TAGS directive.
e.g.
TT2Tags html
TT2Tags
The configuration directives are listed in full below. Consult Template
for further information on their effects within the Template Toolkit.
TT2Tags
Used to set the tags used to indicate Template Toolkit directives
within source templates. A single value can be specified to indicate
a TAG_STYLE, e.g.
TT2Tags html
A pair of values can be used to indicate a START_TAG and END_TAG.
TT2Tags
Note that, unlike the Template Toolkit START_TAG and END_TAG
configuration options, these values are automatically escaped to
remove any special meaning within regular expressions.
TT2Tags [* *] # no need to escape [ or *
By default, the start and end tags are set to "[%" and "%]"
respectively. Thus, directives are embedded in the form: [% INCLUDE
my/file %].
TT2PreChomp
Equivalent to the PRE_CHOMP configuration item. This flag can be set
to have removed any whitespace preceeding a directive, up to and
including the preceeding newline. Default is 'Off'.
TT2PreChomp On
TT2PostChomp
Equivalent to the POST_CHOMP configuration item. This flag can be
set to have any whitespace after a directive automatically removed,
up to and including the following newline. Default is 'Off'.
TT2PostChomp On
TT2Trim
Equivalent to the TRIM configuration item, this flag can be set to
have all surrounding whitespace stripped from template output.
Default is 'Off'.
TT2Trim On
TT2AnyCase
Equivalent to the ANY_CASE configuration item, this flag can be set
to allow directive keywords to be specified in any case. By default,
this setting is 'Off' and all directive (e.g. 'INCLUDE', 'FOREACH',
etc.) should be specified in UPPER CASE only.
TT2AnyCase On
TT2Interpolate
Equivalent to the INTERPOLATE configuration item, this flag can be
set to allow simple variables of the form $var to be embedded within
templates, outside of regular directives. By default, this setting
is 'Off' and variables must appear in the form [% var %], or more
explicitly, [% GET var %].
TT2Interpolate On
TT2IncludePath
Equivalent to the INCLUDE_PATH configuration item. This can be used
to specify one or more directories in which templates are located.
Multiple directories may appear on each TT2IncludePath directive
line, and the directive may be repeated. Directories are searched in
the order defined.
TT2IncludePath /usr/local/tt2/templates
TT2InludePath /home/abw/tt2 /tmp/tt2
Note that this only affects templates which are processed via
directive such as INCLUDE, PROCESS, INSERT, WRAPPER, etc. The full
path of the main template processed by the Apache/mod_perl handler
is generated (by Apache) by appending the request URI to the
DocumentRoot, as per usual. For example, consider the following
configuration extract:
DocumentRoot /usr/local/web/ttdocs
[...]
TT2IncludePath /usr/local/tt2/templates
SetHandler perl-script
PerlHandler Apache::Template
A request with a URI of '/foo/bar.tt2' will cause the handler to
process the file '/usr/local/web/ttdocs/foo/bar.tt2' (i.e.
DocumentRoot + URI). If that file should include a directive such as
[% INCLUDE foo/bar.tt2 %] then that template should exist as the
file '/usr/local/tt2/templates/foo/bar.tt2' (i.e. TT2IncludePath +
template name).
TT2Absolute
Equivalent to the ABSOLUTE configuration item, this flag can be
enabled to allow templates to be processed (via INCLUDE, PROCESS,
etc.) which are specified with absolute filenames.
TT2Absolute On
With the flag enabled a template directive of the form:
[% INCLUDE /etc/passwd %]
will be honoured. The default setting is 'Off' and any attempt to
load a template by absolute filename will result in a 'file'
exception being throw with a message indicating that the ABSOLUTE
option is not set. See Template for further discussion on exception
handling.
TT2Relative
Equivalent to the RELATIVE configuration item. This is similar to
the TT2Absolute option, but relating to files specified with a
relative filename, that is, starting with './' or '../'
TT2Relative On
Enabling the option permits templates to be specifed as per this
example:
[% INCLUDE ../../../etc/passwd %]
As with TT2Absolute, this option is set 'Off', causing a 'file'
exception to be thrown if used in this way.
TT2Delimiter
Equivalent to the DELIMTER configuration item, this can be set to
define an alternate delimiter for separating multiple TT2IncludePath
options. By default, it is set to ':', and thus multiple directories
can be specified as:
TT2IncludePath /here:/there
Note that Apache implicitly supports space-delimited options, so the
following is also valid and defines 3 directories, /here, /there and
/anywhere.
TT2IncludePath /here:/there /anywhere
If you're unfortunate enough to be running Apache on a Win32 system
and you need to specify a ':' in a path name, then set the
TT2Delimiter to an alternate value to avoid confusing the Template
Toolkit into thinking you're specifying more than one directory:
TT2Delimiter ,
TT2IncludePath C:/HERE D:/THERE E:/ANYWHERE
TT2PreProcess
Equivalent to PRE_PROCESS, this option allows one or more templates
to be named which should be processed before the main template. This
can be used to process a global configuration file, add canned
headers, etc. These templates should be located in one of the
TT2IncludePath directories, or specified absolutely if the
TT2Absolute option is set.
TT2PreProcess config header
TT2PostProcess
Equivalent to POST_PROCESS, this option allow one or more templates
to be named which should be processed after the main template, e.g.
to add standard footers. As per TTPreProcess, these should be
located in one of the TT2IncludePath directories, or specified
absolutely if the TT2Absolute option is set.
TT2PostProcess copyright footer
TT2Process
This is equivalent to the PROCESS configuration item. It can be used
to specify one or more templates to be process instead of the main
template. This can be used to apply a standard "wrapper" around all
template files processed by the handler.
TT2Process mainpage
The original template (i.e. whose path is formed from the
DocumentRoot + URI, as explained in the TT2IncludePath item above)
is preloaded and available as the 'template' variable. This a
typical TT2Process template might look like:
[% PROCESS header %]
[% PROCESS $template %]
[% PROCESS footer %]
Note the use of the leading '$' on template to defeat the
auto-quoting mechanism which is applied to INCLUDE, PROCESS, etc.,
directives. The directive would otherwise by interpreted as:
[% PROCESS "template" %]
TT2Wrapper
This is equivalent to the WRAPPER configuration item. It can be used
to specify one or more templates to be wrapped around the content
generated by processing the main page template.
TT2Wrapper sitewrap
The original page template is processed first. The wrapper template
is then processed, with the "content" variable containing the output
generated by processing the main page template.
Multiple wrapper templates can be specified. For example, to wrap
each page in the layout template, and then to wrap that in the
htmlpage template, you would write:
TT2Wrapper htmlpage layout
Or:
TT2Wrapper htmlpage
TT2Wrapper layout
Note that the TT2Wrapper options are specified in "outside-in" order
(i.e. the outer wrapper, followed by the inner wrapper). However,
they are processed in reverse "inside-out" order (i.e. the page
content, followed by the inner wrapper, followed by the outer
wrapper).
TT2Default
This is equivalent to the DEFAULT configuration item. This can be
used to name a template to be used in place of a missing template
specified in a directive such as INCLUDE, PROCESS, INSERT, etc. Note
that if the main template is not found (i.e. that which is mapped
from the URI) then the handler will decline the request, resulting
in a 404 - Not Found. The template specified should exist in one of
the directories named by TT2IncludePath.
TT2Default nonsuch
TT2Error
This is equivalent to the ERROR configuration item. It can be used
to name a template to be used to report errors that are otherwise
uncaught. The template specified should exist in one of the
directories named by TT2IncludePath. When the error template is
processed, the 'error' variable will be set to contain the relevant
error details.
TT2Error error
TT2Variable
This option allows you to define values for simple template
variables. If you have lots of variables to define then you'll
probably want to put them in a config template and pre-process it
with TT2PreProcess.
TT2Variable version 3.14
TT2Constant
This option allows you to define values for constants. These are
similar to regular TT variables, but are resolved once when the
template is compiled.
TT2Constant pi 3.14
TT2ConstantsNamespace
Constants are accessible via the 'constants' namespace by default
(e.g. [% constants.pi %]. This option can be used to provide an
alternate namespace for constants.
TT2ConstantNamespace my
TT2EvalPerl
This is equivalent to the EVAL_PERL configuration item. It can be
enabled to allow embedded [% PERL %] ... [% END %] sections within
templates. It is disabled by default and any PERL sections
encountered will raise 'perl' exceptions with the message 'EVAL_PERL
not set'.
TT2EvalPerl On
TT2LoadPerl
This is equivalent to the LOAD_PERL configuration item which allows
regular Perl modules to be loaded as Template Toolkit plugins via
the USE directive. It is set 'Off' by default.
TT2LoadPerl On
TT2Recursion
This is equivalent to the RECURSION option which allows templates to
recurse into themselves either directly or indirectly. It is set
'Off' by default.
TT2Recursion On
TT2PluginBase
This is equivalent to the PLUGIN_BASE option. It allows multiple
Perl packages to be specified which effectively form a search path
for loading Template Toolkit plugins. The default value is
'Template::Plugin'.
TT2PluginBase My::Plugins Your::Plugins
TT2AutoReset
This is equivalent to the AUTO_RESET option and is enabled by
default. It causes any template BLOCK definitions to be cleared
before each main template is processed.
TT2AutoReset Off
TT2CacheSize
This is equivalent to the CACHE_SIZE option. It can be used to limit
the number of compiled templates that are cached in memory. The
default value is undefined and all compiled templates will be cached
in memory. It can be set to a specified numerical value to define
the maximum number of templates, or to 0 to disable caching
altogether.
TT2CacheSize 64
TT2CompileExt
This is equivalent to the COMPILE_EXT option. It can be used to
specify a filename extension which the Template Toolkit will use for
writing compiled templates back to disk, thus providing cache
persistance.
TT2CompileExt .ttc
TT2CompileDir
This is equivalent to the COMPILE_DIR option. It can be used to
specify a root directory under which compiled templates should be
written back to disk for cache persistance. Any TT2IncludePath
directories will be replicated in full under this root directory.
TT2CompileDir /var/tt2/cache
TT2Debug
This is equivalent to the DEBUG option which enables Template
Toolkit debugging. The main effect is to raise additional warnings
when undefined variables are used but is likely to be expanded in a
future release to provide more extensive debugging capabilities.
TT2Debug On
TT2Tolerant
This is equivalent to the TOLERANT option which makes the Template
Toolkit providers tolerant to errors.
TT2Tolerant On
TT2Headers
Allows you to specify which HTTP headers you want added to the
response. Current permitted values are: 'modified' (Last-Modified),
'length' (Content-Length), 'etag' (E-Tag) or 'all' (all the above).
TT2Headers all
TT2Params
Allows you to specify which parameters you want defined as template
variables. Current permitted values are 'uri', 'env' (hash of
environment variables), 'params' (hash of CGI parameters), 'pnotes'
(the request pnotes hash), 'cookies' (hash of cookies), 'uploads' (a
list of Apache::Upload instances), 'request' (the Apache::Request
object) or 'all' (all of the above).
TT2Params uri env params uploads request
When set, these values can then be accessed from within any template
processed:
The URI is [% uri %]
Server name is [% env.SERVER_NAME %]
CGI params are:
[% FOREACH key = params.keys %]
| [% key %] | [% params.$key %] |
[% END %]
TT2ServiceModule
The modules have been designed in such a way as to make it easy to
subclass the Template::Service::Apache module to create your own
custom services.
For example, the regular service module does a simple 1:1 mapping of
URI to template using the request filename provided by Apache, but
you might want to implement an alternative scheme. You might prefer,
for example, to map multiple URIs to the same template file, but to
set some different template variables along the way.
To do this, you can subclass Template::Service::Apache and redefine
the appropriate methods. The template() method performs the task of
mapping URIs to templates and the params() method sets up the
template variable parameters. Or if you need to modify the HTTP
headers, then headers() is the one for you.
The TT2ServiceModule option can be set to indicate the name of your
custom service module. The following trivial example shows how you
might subclass Template::Service::Apache to add an additional
parameter, in this case as the template variable 'message'.
package My::Service::Module;
use base qw( Template::Service::Apache );
sub params {
my $self = shift;
my $params = $self->SUPER::params(@_);
$params->{ message } = 'Hello World';
return $params;
}
PerlModule Apache::Template
TT2ServiceModule My::Service::Module
CONFIGURATION MERGING
The Apache::Template module creates a separate service for each virtual
server. Each virtual server can have its own configuration. Any globally
defined options will be merged with any server-specific ones.
The following examples illustrates two separate virtual servers being
configured in one Apache configuration file.
PerlModule Apache::Template
TT2IncludePath /usr/local/tt2/templates
TT2Params request params
TT2Wrapper html/page
NameVirtualHost 127.0.0.1
ServerName shoveit
SetHandler perl-script
PerlHandler Apache::Template
TT2Wrapper layout_a
ServerName kickflip
SetHandler perl-script
PerlHandler Apache::Template
TT2Wrapper layout_b
In this example, the "shoveit" virtual host will be configured as if
written:
PerlModule Apache::Template
TT2IncludePath /usr/local/tt2/templates
TT2Params request params
TT2Wrapper html/page
TT2Wrapper layout_a
The second "TTWrapper" option ("layout_a") is added to the shared
configuration block.
The "kickflip" virtual host will be configured as if written:
PerlModule Apache::Template
TT2IncludePath /usr/local/tt2/templates
TT2Params request params
TT2Wrapper html/page
TT2Wrapper layout_b
Here, the "layout_b" wrapper template is used instead of "layout_a".
Apache::Template does not correctly handle different configurations for
separate directories, location or files within the same virtual server.
AUTHOR
Andy Wardley
This module has been derived in part from the 'Grover' module by Darren
Chamberlain (darren@boston.com). Darren kindly donated his code for
integration into the Apache::Template module.
VERSION
This is version 0.08 of the Apache::Template module.
COPYRIGHT
Copyright (C) 1996-2003 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
For further information about the Template Toolkit, see Template or
http://www.template-toolkit.org/