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.

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

    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/

