|
Apache::Template - Apache/mod_perl interface to the Template Toolkit |
Apache::Template - Apache/mod_perl interface to the Template Toolkit
# 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.
<Files *.tt2>
SetHandler perl-script
PerlHandler Apache::Template
</Files>
<Location /tt2>
SetHandler perl-script
PerlHandler Apache::Template
</Location>
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 for further information.
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 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 On
TT2PostChomp On
TT2Trim On
TT2AnyCase On
$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 /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
<Files *.tt2>
SetHandler perl-script
PerlHandler Apache::Template
</Files>
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 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 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.
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 config header
TT2PostProcess copyright footer
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" %]
TT2Default nonsuch
TT2Error error
TT2EvalPerl On
TT2LoadPerl On
TT2Recursion On
TT2PluginBase My::Plugins Your::Plugins
TT2AutoReset Off
TT2CacheSize 64
TT2CompileExt .ttc
TT2CompileDir /var/tt2/cache
TT2Debug On
TT2Headers all
TT2Params uri env params uploads
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:
<table>
[% FOREACH key = params.keys %]
<tr>
<td>[% key %]</td> <td>[% params.$key %]</td>
</tr>
[% END %]
</table>
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'.
<perl>
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;
}
</perl>
PerlModule Apache::Template
TT2ServiceModule My::Service::Module
The Apache::Template module will now correctly merge multiple configurations for different virtual server and/or directories. For example:
PerlModule Apache::Template
TT2PostChomp On
TT2IncludePath /usr/local/tt2/shared
<Location /tom>
TT2IncludePath /home/tom/tt2
TT2EvalPerl On
</Location>
<Location /dick>
TT2IncludePath /home/dick/tt2
TT2Trim On
TT2PostChomp Off
</Location>
Here, all URI's starting '/tom' have an effective TT2IncludePath of:
TT2IncludePath /usr/local/tt2/shared /home/tom/tt2
and those starting '/dick' have:
TT2IncludePath /usr/local/tt2/shared /home/dick/tt2
Similarly, different options such as TT2PostChomp, TT2EvalPerl, etc., should enabled/disabled appropriately for different locations.
Andy Wardley <abw@kfs.org>
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.
This is version 0.06 of the Apache::Template module.
Copyright (C) 1996-2002 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.
For further information about the Template Toolkit, see Template or http://www.template-toolkit.org/
|
Apache::Template - Apache/mod_perl interface to the Template Toolkit |