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.
<Files *.tt2>
    SetHandler      perl-script
    PerlHandler     Apache::Template
</Files>

<Location /tt2>
    SetHandler      perl-script
    PerlHandler     Apache::Template
</Location>

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.

UPGRADING FROM EARLIER VERSIONS OF Apache::Template

If you are upgrading from an earlier version of Apache::Template (e.g. 0.08 or earlier) then you should pay particular attention to the changes in the TT2Headers option in version 0.09.

The Content-Type header can now be controlled by the TT2Headers option (to enable or disable it) and by the TT2ContentType option (to set a specific Content-Type).

If you don't specify any TT2Headers option, then it will default to sending the Content-Type header only, emulating the existing behaviour of Apache::Template 0.08 and earlier. Thus the default is equivalent to the following:

TT2Headers      type              # default

If you do specify a TT2Headers option, then you must now explicitly add the 'type' value to have Apache::Template send the Content-Type header.

TT2Headers      type length

If you don't specify 'type' in the TT2Headers option then Apache::Template will not add a Content-Type header.

The default value for Content-Type is 'text/html' but can now be changed using the TT2ContentType option.

TT2ContentType  text/xml

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

<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

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: 'type' (Content-Type), 'length' (Content-Length), 'modified' (Last-Modified) and 'etag' (E-Tag).

TT2Headers      type length

It can also be set to 'all' to enable all headers.

TT2Headers      all

If the TT2Headers option is not specified, then it default to 'type', sending the Content-Type header set to the value of TT2ContentType or 'text/html' if undefined.

TT2Headers      type    # default - same as no TT2Headers option

The option can be set to 'none' to disable all headers, including the Content-Type.

TT2Headers      none

TT2ContentType

This option can be used to set a Content-Type other than the default value of 'text/html'.

TT2ContentType   text/xml

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:
<table>
[% FOREACH key = params.keys %]
   <tr>
 <td>[% key %]</td>  <td>[% params.$key %]</td>
   </tr>
[% END %]
</table>

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'.

<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

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

<VirtualHost 127.0.0.1>
    ServerName     shoveit
    SetHandler     perl-script
    PerlHandler    Apache::Template
    TT2Wrapper     layout_a
</VirtualHost>

<VirtualHost 127.0.0.1>
   ServerName     kickflip
   SetHandler     perl-script
   PerlHandler    Apache::Template
   TT2Wrapper     layout_b
</VirtualHost>

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 <abw@wardley.org>, with contributions from Darren Chamberlain (who wrote the 'Grover' module which was integrated into Apache::Template), Mark Fowler, Randal Schwartz, Tony Payne and Rick Myers.

VERSION

This is version 0.09 of the Apache::Template module.

COPYRIGHT

Copyright (C) 1996-2004 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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)