ENCODING

    my $template = Template->new({
        ENCODING => 'utf8',
    });

A template which starts with a Unicode byte order mark (BOM) will have its encoding detected automatically.

START_TAG, END_TAG

    [% example %]

Any Perl regex characters can be used and therefore should be escaped (or use the Perl "quotemeta" function) if they are intended to represent literal characters.

    my $template = Template->new({
        START_TAG => quotemeta('<+'),
        END_TAG   => quotemeta('+>'),
    });

Example:

    <+ INCLUDE foobar +>

The "TAGS" directive can also be used to set the "START_TAG" and "END_TAG" values on a per-template file basis.

    [% TAGS <+ +> %]

OUTLINE_TAG

    my $template = Template->new({
        OUTLINE_TAG => '%%',
    });

This allows you to use both inline and outline tags like so:

    %% IF user
    Hello [% user.name %]
    %% END

The "OUTLINE_TAG" string (or regex) must appear at the start of a line. The directive continues until the end of the line. The newline character at the end of the line is considered to be the invisible end-of-directive marker and is removed.

TAG_STYLE

    my $template = Template->new({
        TAG_STYLE => 'star',
    });

Available styles are:

    template    [% ... %]               (default)
    template1   [% ... %] or %% ... %%  (TT version 1)
    metatext    %% ... %%               (Text::MetaText)
    star        [* ... *]               (TT alternate)
    php         <? ... ?>               (PHP)
    asp         <% ... %>               (ASP)
    mason       <% ...  >               (HTML::Mason)
    html        <!-- ... -->            (HTML comments)

The "outline" style uses the default markers for "START_TAG" and "END_TAG" ("[%" and "%]" respectively) and additionally defines "OUTLINE_TAG" to be "%%".

    my $template = Template->new({
        TAG_STYLE => 'outline',
    });

This allows you to use both inline and outline tags like so:

    %% IF user
    Hello [% user.name %]
    %% END

Any values specified for "START_TAG", "END_TAG" and/or "OUTLINE_TAG" will override those defined by a "TAG_STYLE".

The "TAGS" directive may also be used to set a "TAG_STYLE"

    [% TAGS html %]
    <!-- INCLUDE header -->

PRE_CHOMP, POST_CHOMP

Example:

    Foo
    [% a = 10 %]
    Bar

Output:

    Foo

    Bar

The "PRE_CHOMP" and "POST_CHOMP" options can help to clean up some of this extraneous whitespace. Both are disabled by default.

    my $template = Template->new({
        PRE_CHOMP  => 1,
        POST_CHOMP => 1,
    });

With "PRE_CHOMP" set to 1, the newline and whitespace preceding a directive at the start of a line will be deleted. This has the effect of concatenating a line that starts with a directive onto the end of the previous line.

        Foo <----------.
                       |
    ,---(PRE_CHOMP)----'
    |
    `-- [% a = 10 %] --.
                       |
    ,---(POST_CHOMP)---'
    |
    `-> Bar

With "POST_CHOMP" set to 1, any whitespace after a directive up to and including the newline will be deleted. This has the effect of joining a line that ends with a directive onto the start of the next line.

If "PRE_CHOMP" or "POST_CHOMP" is set to 2, all whitespace including any number of newline will be removed and replaced with a single space. This is useful for HTML, where (usually) a contiguous block of whitespace is rendered the same as a single space.

With "PRE_CHOMP" or "POST_CHOMP" set to 3, all adjacent whitespace (including newlines) will be removed entirely.

These values are defined as "CHOMP_NONE", "CHOMP_ONE", "CHOMP_COLLAPSE" and "CHOMP_GREEDY" constants in the Template::Constants module. "CHOMP_ALL" is also defined as an alias for "CHOMP_ONE" to provide backwards compatibility with earlier version of the Template Toolkit.

Additionally the chomp tag modifiers listed below may also be used for the "PRE_CHOMP" and "POST_CHOMP" configuration.

     my $template = Template->new({
        PRE_CHOMP  => '~',
        POST_CHOMP => '-',
     });

"PRE_CHOMP" and "POST_CHOMP" can be activated for individual directives by placing a '"-"' immediately at the start and/or end of the directive.

    [% FOREACH user IN userlist %]
       [%- user -%]
    [% END %]

This has the same effect as "CHOMP_ONE" in removing all whitespace before or after the directive up to and including the newline. The template will be processed as if written:

    [% FOREACH user IN userlist %][% user %][% END %]

To remove all whitespace including any number of newlines, use the ('"~"') tilde character instead.

    [% FOREACH user IN userlist %]

       [%~ user ~%]

    [% END %]

To collapse all whitespace to a single space, use the '"="' equals sign character.

    [% FOREACH user IN userlist %]

       [%= user =%]

    [% END %]

Here the template is processed as if written:

    [% FOREACH user IN userlist %] [% user %] [% END %]

If you have "PRE_CHOMP" or "POST_CHOMP" set as configuration options then you can use the '"+"' plus sign to disable any chomping options (i.e. leave the whitespace intact) on a per-directive basis.

    [% FOREACH user IN userlist %]
    User: [% user +%]
    [% END %]

With "POST_CHOMP" set to "CHOMP_ONE", the above example would be parsed as if written:

    [% FOREACH user IN userlist %]User: [% user %]
    [% END %]

For reference, the "PRE_CHOMP" and "POST_CHOMP" configuration options may be set to any of the following:

     Constant      Value   Tag Modifier
     ----------------------------------
     CHOMP_NONE      0          +
     CHOMP_ONE       1          -
     CHOMP_COLLAPSE  2          =
     CHOMP_GREEDY    3          ~

TRIM

By example, the following "BLOCK" definition

    [% BLOCK foo %]
    Line 1 of foo
    [% END %]

will be processed is as ""\nLine 1 of foo\n"". When "INCLUDE"d, the surrounding newlines will also be introduced.

    before
    [% INCLUDE foo %]
    after

Generated output:

    before

    Line 1 of foo

    after

With the "TRIM" option set to any true value, the leading and trailing newlines (which count as whitespace) will be removed from the output of the "BLOCK".

    before
    Line 1 of foo
    after

The "TRIM" option is disabled (0) by default.

INTERPOLATE

    my $template = Template->new({
        INTERPOLATE => 1,
    });

Variables should be prefixed by a '"$"' dollar sign to identify them. Curly braces '"{"' and '"}"' can be used in the familiar Perl/shell style to explicitly scope the variable name where required.

    # INTERPOLATE => 0
    <a href="http://[% server %]/[% help %]">
    <img src="[% images %]/help.gif"></a>
    [% myorg.name %]

    # INTERPOLATE => 1
    <a href="http://$server/$help">
    <img src="$images/help.gif"></a>
    $myorg.name

    # explicit scoping with {  }
    <img src="$images/${icon.next}.gif">

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 "INTERPOLATE" or split the templates in several smaller files or blocks which can then be joined backed together via "PROCESS" or "INCLUDE".

ANYCASE

    # ANYCASE => 0 (default)
    [% INCLUDE foobar %]        # OK
    [% include foobar %]        # ERROR
    [% include = 10   %]        # OK, 'include' is a variable

    # ANYCASE => 1
    [% INCLUDE foobar %]        # OK
    [% include foobar %]        # OK
    [% include = 10   %]        # ERROR, 'include' is reserved word

One side-effect of enabling "ANYCASE" is that you cannot use a variable of the same name as a reserved word, regardless of case. The reserved words are currently:

    GET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER
    IF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE
    USE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META
    TRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP
    CLEAR TO STEP AND OR NOT MOD DIV END

The only lower case reserved words that cannot be used for variables, regardless of the "ANYCASE" option, are the operators:

    and or not mod div

INCLUDE_PATH

    my $template = Template->new({
        INCLUDE_PATH => '/usr/local/templates',
    });

    my $template = Template->new({
        INCLUDE_PATH => '/usr/local/templates:/tmp/my/templates',
    });

    my $template = Template->new({
        INCLUDE_PATH => [ '/usr/local/templates',
                          '/tmp/my/templates' ],
    });

On Win32 systems, a little extra magic is invoked, ignoring delimiters that have '":"' colon followed by a '"/"' slash or '"\"' blackslash. This avoids confusion when using directory names like '"C:\Blah Blah"'.

When specified as a list, the "INCLUDE_PATH" path can contain elements which dynamically generate a list of "INCLUDE_PATH" directories. These generator elements can be specified as a reference to a subroutine or an object which implements a "paths()" method.

    my $template = Template->new({
        INCLUDE_PATH => [ '/usr/local/templates',
                          \&incpath_generator,
                          My::IncPath::Generator->new( ... ) ],
    });

Each time a template is requested and the "INCLUDE_PATH" examined, the subroutine or object method will be called. A reference to a list of directories should be returned. Generator subroutines should report errors using "die()". Generator objects should return undef and make an error available via its "error()" method.

For example:

    sub incpath_generator {
        # ...some code...

        if ($all_is_well) {
            return \@list_of_directories;
        }
        else {
            die "cannot generate INCLUDE_PATH...\n";
        }
    }

or:

    package My::IncPath::Generator;

    # Template::Base (or Class::Base) provides error() method
    use Template::Base;
    use base qw( Template::Base );

    sub paths {
        my $self = shift;

        # ...some code...

        if ($all_is_well) {
            return \@list_of_directories;
        }
        else {
            return $self->error("cannot generate INCLUDE_PATH...\n");
        }
    }

    1;

DELIMITER

    my $template = Template->new({
        DELIMITER    => '; ',
        INCLUDE_PATH => 'C:/HERE/NOW; D:/THERE/THEN',
    });

On Win32 systems, the default delimiter is a little more intelligent, splitting paths only on '":"' colon characters that aren't followed by a '"/"' slash character. This means that the following should work as planned, splitting the "INCLUDE_PATH" into 2 separate directories, "C:/foo" and "C:/bar".

    # on Win32 only
    my $template = Template->new({
        INCLUDE_PATH => 'C:/Foo:C:/Bar'
    });

However, if you're using Win32 then it's recommended that you explicitly set the "DELIMITER" character to something else (e.g. '";"' semicolon) rather than rely on this subtle magic.

ABSOLUTE

    my $template = Template->new({
        ABSOLUTE => 1,
    });

    # this is why it's disabled by default
    [% INSERT /etc/passwd %]

On Win32 systems, the regular expression for matching absolute pathnames is tweaked slightly to also detect filenames that start with a driver letter and colon, such as:

    C:/Foo/Bar

RELATIVE

    my $template = Template->new({
        RELATIVE => 1,
    });

    [% INCLUDE ../logs/error.log %]

DEFAULT

    my $template = Template->new({
        DEFAULT => 'notfound.html',
    });

If a non-existent template is requested through the Template process() method, or by an "INCLUDE", "PROCESS" or "WRAPPER" directive, then the "DEFAULT" template will instead be processed, if defined. Note that the "DEFAULT" template is not used when templates are specified with absolute or relative filenames, or as a reference to a input file handle or text string.

BLOCKS

    my $template = Template->new({
        BLOCKS => {
            header  => 'The Header.  [% title %]',
            footer  => sub { return $some_output_text },
            another => Template::Document->new({ ... }),
        },
    });

VIEWS

    my $template = Template->new({
        VIEWS => {
            my_view => { prefix => 'my_templates/' },
        },
    });

Be aware of the fact that Perl's hash array are unordered, so if you want to specify multiple views of which one or more are based on other views, then you should use a list reference to preserve the order of definition.

    my $template = Template->new({
        VIEWS => [
            bottom => { prefix => 'bottom/' },
            middle => { prefix => 'middle/', base => 'bottom' },
            top    => { prefix => 'top/',    base => 'middle' },
        ],
    });

AUTO_RESET

The "BLOCKS" item may be used to specify a default set of block definitions for the Template::Context object. Subsequent "BLOCK" definitions in templates will over-ride these but they will be reinstated on each reset if "AUTO_RESET" is enabled (default), or if the Template::Context reset() method is called.

RECURSION

VARIABLES

    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,
        },
    };

CONSTANTS

    my $template = Template->new({
        CONSTANTS => {
            title   => 'A Demo Page',
            author  => 'Joe Random Hacker',
            version => 3.14,
        },
    };

CONSTANT_NAMESPACE

    [% constants.title %]

The "CONSTANTS_NAMESPACE" 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 %]

NAMESPACE

Under the hood, the Template 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 Template::Namespace::Constants for an example of what a namespace handler looks like on the inside.

PRE_PROCESS, POST_PROCESS

    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 '":"'. This delimiter string can be changed via the "DELIMITER" option.

    my $template = Template->new({
        PRE_PROCESS  => 'config:header',
        POST_PROCESS => 'footer',
    };

The "PRE_PROCESS" and "POST_PROCESS" 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' %]
    <html>
      <head>
        <title>[% title %]</title>
      </head>
      <body bgcolor="[% bgcolor %]">

footer:

        <hr>
        Version [% version %]
      </body>
    </html>

The Template::Document object representing the main template being processed is available within "PRE_PROCESS" and "POST_PROCESS" templates as the "template" variable. Metadata items defined via the "META" directive may be accessed accordingly.

    $template->process('mydoc.html', $vars);

mydoc.html:

    [% META title = 'My Document Title' %]
    blah blah blah
    ...

header:

    <html>
      <head>
        <title>[% template.title %]</title>
      </head>
      <body bgcolor="[% bgcolor %]">

PROCESS

    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 "template" variable. Metadata items can be inspected and the template can be processed by specifying it as a variable reference (i.e. prefixed by "$") to an "INCLUDE", "PROCESS" or "WRAPPER" directive.

content:

    <html>
      <head>
        <title>[% template.title %]</title>
      </head>
      <body>
    <!-- begin content -->
    [% PROCESS $template %]
    <!-- end content -->
        <hr>
        &copy; Copyright [% template.copyright %]
      </body>
    </html>

foo.html:

    [% META
       title     = 'The Foo Page'
       author    = 'Fred Foo'
       copyright = '2000 Fred Foo'
    %]
    <h1>[% template.title %]</h1>
    Welcome to the Foo Page, blah blah blah

output:

    <html>
      <head>
        <title>The Foo Page</title>
      </head>
      <body>
    <!-- begin content -->
    <h1>The Foo Page</h1>
    Welcome to the Foo Page, blah blah blah
    <!-- end content -->
        <hr>
        &copy; Copyright 2000 Fred Foo
      </body>
    </html>

WRAPPER

    my $template = Template->new({
        WRAPPER => 'wrapper',
    };

    # process 'foo' then wrap in 'wrapper'
    $template->process('foo', { message => 'Hello World!' });

wrapper:

    <wrapper>
    [% content %]
    </wrapper>

foo:

    This is the foo file!
    Message: [% message %]

The output generated from this example is:

    <wrapper>
    This is the foo file!
    Message: Hello World!
    </wrapper>

You can specify more than one "WRAPPER" template by setting the value to be a reference to a list of templates. The "WRAPPER" 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:

    <outer>
    [% content %]
    </outer>

inner:

    <inner>
    [% content %]
    </inner>

The output generated is then:

    <outer>
    <inner>
    This is the foo file!
    Message: Hello World!
    </inner>
    </outer>

One side-effect of the "inside-out" processing of the "WRAPPER" configuration item (and also the "WRAPPER" 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'
       }
    %]

    <p>
    Welcome to the page that tells you everything about foo
    blah blah blah...
    </p>

The "foo" template is processed before the wrapper template meaning that the "page" data structure will be defined for use in the wrapper template.

wrapper:

    <html>
      <head>
        <title>[% page.title %]</title>
      </head>
      <body>
        <h1>[% page.title %]</h1>
        <h2>[% page.subtitle %]</h1>
        <h3>by [% page.author %]</h3>
        [% content %]
      </body>
    </html>

It achieves the same effect as defining "META" items which are then accessed via the "template" variable (which you are still free to use within "WRAPPER" templates), but gives you more flexibility in the type and complexity of data that you can define.

ERROR

If specified as a single value then that template will be processed for all uncaught exceptions.

    my $template = Template->new({
        ERROR => 'error.html'
    });

If the "ERROR" item is a hash reference the keys are assumed to be exception types and the relevant template for a given exception will be selected. A "default" template may be provided for the general case. Note that "ERROR" can be pluralised to "ERRORS" if you find it more appropriate in this case.

    my $template = Template->new({
        ERRORS => {
            user     => 'user/index.html',
            dbi      => 'error/database',
            default  => 'error/default',
        },
    });

In this example, any "user" exceptions thrown will cause the user/index.html template to be processed, "dbi" errors are handled by error/database and all others by the error/default template. Any "PRE_PROCESS" and/or "POST_PROCESS" templates will also be applied to these error templates.

Note that exception types are hierarchical and a "foo" handler will catch all "foo.*" errors (e.g. "foo.bar", "foo.bar.baz") if a more specific handler isn't defined. Be sure to quote any exception types that contain periods to prevent Perl concatenating them into a single string (i.e. "user.passwd" is parsed as 'user'.'passwd').

    my $template = Template->new({
        ERROR => {
            'user.login'  => 'user/login.html',
            'user.passwd' => 'user/badpasswd.html',
            'user'        => 'user/index.html',
            'default'     => 'error/default',
        },
    });

In this example, any template processed by the $template object, or other templates or code called from within, can raise a "user.login" exception and have the service redirect to the user/login.html template. Similarly, a "user.passwd" exception has a specific handling template, user/badpasswd.html, while all other "user" or "user.*" exceptions cause a redirection to the user/index.html page. All other exception types are handled by error/default.

Exceptions can be raised in a template using the "THROW" directive,

    [% THROW user.login 'no user id: please login' %]

or by calling the throw() method on the current Template::Context object,

    $context->throw('user.passwd', 'Incorrect Password');
    $context->throw('Incorrect Password');    # type 'undef'

or from Perl code by calling "die()" with a Template::Exception object,

    die (Template::Exception->new('user.denied', 'Invalid User ID'));

or by simply calling die() with an error string. This is automagically caught and converted to an exception of '"undef"' type which can then be handled in the usual way.

    die "I'm sorry Dave, I can't do that";

Note that the '"undef"' we're talking about here is a literal string rather than Perl's "undef" used to represent undefined values.

EVAL_PERL

When using compiled templates (see "Caching and Compiling Options"), the "EVAL_PERL" has an affect when the template is compiled, and again when the templates is subsequently processed, possibly in a different context to the one that compiled it.

If the "EVAL_PERL" is set when a template is compiled, then all "PERL" and "RAWPERL" blocks will be included in the compiled template. If the "EVAL_PERL" option isn't set, then Perl code will be generated which always throws a '"perl"' exception with the message '"EVAL_PERL not set"' whenever the compiled template code is run.

Thus, you must have "EVAL_PERL" set if you want your compiled templates to include "PERL" and "RAWPERL" blocks.

At some point in the future, using a different invocation of the Template Toolkit, you may come to process such a pre-compiled template. Assuming the "EVAL_PERL" option was set at the time the template was compiled, then the output of any "RAWPERL" blocks will be included in the compiled template and will get executed when the template is processed. This will happen regardless of the runtime "EVAL_PERL" status.

Regular "PERL" blocks are a little more cautious, however. If the "EVAL_PERL" flag isn't set for the current context, that is, the one which is trying to process it, then it will throw the familiar '"perl"' exception with the message, '"EVAL_PERL not set"'.

Thus you can compile templates to include "PERL" blocks, but optionally disable them when you process them later. Note however that it is possible for a "PERL" block to contain a Perl ""BEGIN { # some code }"" block which will always get run regardless of the runtime "EVAL_PERL" status. Thus, if you set "EVAL_PERL" when compiling templates, it is assumed that you trust the templates to Do The Right Thing. Otherwise you must accept the fact that there's no bulletproof way to prevent any included code from trampling around in the living room of the runtime environment, making a real nuisance of itself if it really wants to. If you don't like the idea of such uninvited guests causing a bother, then you can accept the default and keep "EVAL_PERL" disabled.

OUTPUT

example 1 (file name):

    my $template = Template->new({
        OUTPUT => "/tmp/foo",
    });

example 2 (text string):

    my $output   = '';
    my $template = Template->new({
        OUTPUT => \$output,
    });

example 3 (file handle):

    open (TOUT, ">", $file) || die "$file: $!\n";
    my $template = Template->new({
        OUTPUT => \*TOUT,
    });

example 4 (subroutine):

    sub output { my $out = shift; print "OUTPUT: $out" }
    my $template = Template->new({
        OUTPUT => \&output,
    });

example 5 (array reference):

    my $template = Template->new({
        OUTPUT => \@output,
    })

example 6 (Apache/mod_perl handler):

    sub handler {
        my $r = shift;
        my $t = Template->new({
            OUTPUT => $r,
        });
        ...
    }

The default "OUTPUT" location be overridden by passing a third parameter to the Template process() method. This can be specified as any of the above argument types.

    $t->process($file, $vars, "/tmp/foo");
    $t->process($file, $vars, \$output);
    $t->process($file, $vars, \*MYGLOB);
    $t->process($file, $vars, \@output);
    $t->process($file, $vars, $r);  # Apache::Request
    ...

OUTPUT_PATH

    my $template = Template->new({
        INCLUDE_PATH => "/tmp/src",
        OUTPUT_PATH  => "/tmp/dest",
    });

    my $vars = {
        ...
    };

    foreach my $file ('foo.html', 'bar.html') {
        $template->process($file, $vars, $file)
            || die $template->error();
    }

This example will read the input files /tmp/src/foo.html and /tmp/src/bar.html and write the processed output to /tmp/dest/foo.html and /tmp/dest/bar.html, respectively.

STRICT

When the "STRICT" option is set, the use of any undefined variables or values will cause an exception to be throw. The exception will have a "type" of "var.undefined" and a message of the form "undefined variable: xxx".

    my $template = Template->new(
        STRICT => 1
    );

DEBUG

    use Template::Constants qw( :debug );

    my $template = Template->new({
        DEBUG => DEBUG_PARSER | DEBUG_PROVIDER,
    });

For convenience, you can also provide a string containing a list of lower case debug options, separated by any non-word characters.

    my $template = Template->new({
        DEBUG => 'parser, provider',
    });

The following "DEBUG_XXXX" flags can be used:

DEBUG_SERVICE

Enables general debugging messages for the Template::Service module.

DEBUG_CONTEXT

Enables general debugging messages for the Template::Context module.

DEBUG_PROVIDER

Enables general debugging messages for the Template::Provider module.

DEBUG_PLUGINS

Enables general debugging messages for the Template::Plugins module.

DEBUG_FILTERS

Enables general debugging messages for the Template::Filters module.

DEBUG_PARSER

This flag causes the Template::Parser to generate debugging messages that show the Perl code generated by parsing and compiling each template.

DEBUG_UNDEF

This option causes the Template Toolkit to throw an '"undef"' error whenever it encounters an undefined variable value.

DEBUG_DIRS

This option causes the Template Toolkit to generate comments indicating the source file, line and original text of each directive in the template. These comments are embedded in the template output using the format defined in the "DEBUG_FORMAT" configuration item, or a simple default format if unspecified.

For example, the following template fragment:

    Hello World
    

would generate this output:

    ## input text line 1 :  ##
    Hello
    ## input text line 2 : World ##
    World
    

DEBUG_ALL

Enables all debugging messages.

DEBUG_CALLER

This option causes all debug messages that aren't newline terminated to have the file name and line number of the caller appended to them.

DEBUG_FORMAT

    my $template = Template->new({
        DEBUG => 'dirs',
        DEBUG_FORMAT => '<!-- $file line $line : [% $text %] -->',
    });

The following template fragment:

    [% foo = 'World' %]
    Hello [% foo %]

would then generate this output:

    <!-- input text line 2 : [% foo = 'World' %] -->
    Hello <!-- input text line 3 : [% foo %] -->World

The DEBUG directive can also be used to set a debug format within a template.

    [% DEBUG format '<!-- $file line $line : [% $text %] -->' %]

CACHE_SIZE

By default, the "CACHE_SIZE" is undefined and all compiled templates are cached. When set to any positive value, the cache will be limited to storing no more than that number of compiled templates. When a new template is loaded and compiled and the cache is full (i.e. the number of entries == "CACHE_SIZE"), the least recently used compiled template is discarded to make room for the new one.

The "CACHE_SIZE" can be set to 0 to disable caching altogether.

    my $template = Template->new({
        CACHE_SIZE => 64,   # only cache 64 compiled templates
    });

    my $template = Template->new({
        CACHE_SIZE => 0,   # don't cache any compiled templates
    });

As well as caching templates as they are found, the Template::Provider also implements negative caching to keep track of templates that are not found. This allows the provider to quickly decline a request for a template that it has previously failed to locate, saving the effort of going to look for it again. This is useful when an "INCLUDE_PATH" includes multiple providers, ensuring that the request is passed down through the providers as quickly as possible.

STAT_TTL

    my $provider = Template::Provider->new({
        STAT_TTL => 60,  # one minute
    });

The default value is 1 (second). You'll probably want to set this to a higher value if you're running the Template Toolkit inside a persistent web server application (e.g. mod_perl). For example, set it to 60 and the provider will only look for changes to templates once a minute at most. However, during development (or any time you're making frequent changes to templates) you'll probably want to keep it set to a low value so that you don't have to wait for the provider to notice that your templates have changed.

COMPILE_EXT

    my $template = Template->new({
        COMPILE_EXT => '.ttc',
    });

If "COMPILE_EXT" is defined (and "COMPILE_DIR" isn't, see below) then compiled template files with the "COMPILE_EXT" extension will be written to the same directory from which the source template files were loaded.

Compiling and subsequent reuse of templates happens automatically whenever the "COMPILE_EXT" or "COMPILE_DIR" options are set. The Template Toolkit will automatically reload and reuse compiled files when it finds them on disk. If the corresponding source file has been modified since the compiled version as written, then it will load and re-compile the source and write a new compiled version to disk.

This form of cache persistence offers significant benefits in terms of time and resources required to reload templates. Compiled templates can be reloaded by a simple call to Perl's "require()", leaving Perl to handle all the parsing and compilation. This is a Good Thing.

COMPILE_DIR

    my $template = Template->new({
        COMPILE_DIR => '/tmp/ttc',
    });

The "COMPILE_EXT" option may also be specified to have a consistent file extension added to these files.

    my $template1 = Template->new({
        COMPILE_DIR => '/tmp/ttc',
        COMPILE_EXT => '.ttc1',
    });

    my $template2 = Template->new({
        COMPILE_DIR => '/tmp/ttc',
        COMPILE_EXT => '.ttc2',
    });

When "COMPILE_EXT" is undefined, the compiled template files have the same name as the original template files, but reside in a different directory tree.

Each directory in the "INCLUDE_PATH" is replicated in full beneath the "COMPILE_DIR" directory. This example:

    my $template = Template->new({
        COMPILE_DIR  => '/tmp/ttc',
        INCLUDE_PATH => '/home/abw/templates:/usr/share/templates',
    });

would create the following directory structure:

    /tmp/ttc/home/abw/templates/
    /tmp/ttc/usr/share/templates/

Files loaded from different "INCLUDE_PATH" directories will have their compiled forms save in the relevant "COMPILE_DIR" directory.

On Win32 platforms a filename may by prefixed by a drive letter and colon. e.g.

    C:/My Templates/header

The colon will be silently stripped from the filename when it is added to the "COMPILE_DIR" value(s) to prevent illegal filename being generated. Any colon in "COMPILE_DIR" elements will be left intact. For example:

    # Win32 only
    my $template = Template->new({
        DELIMITER    => ';',
        COMPILE_DIR  => 'C:/TT2/Cache',
        INCLUDE_PATH => 'C:/TT2/Templates;D:/My Templates',
    });

This would create the following cache directories:

    C:/TT2/Cache/C/TT2/Templates
    C:/TT2/Cache/D/My Templates

PLUGINS

    my $template = Template->new({
        PLUGINS => {
            cgi => 'MyOrg::Template::Plugin::CGI',
            foo => 'MyOrg::Template::Plugin::Foo',
            bar => 'MyOrg::Template::Plugin::Bar',
        },
    });

The recommended convention is to specify these plugin names in lower case. The Template Toolkit first looks for an exact case-sensitive match and then tries the lower case conversion of the name specified.

    [% USE Foo %]      # look for 'Foo' then 'foo'

If you define all your "PLUGINS" with lower case names then they will be located regardless of how the user specifies the name in the USE directive. If, on the other hand, you define your "PLUGINS" with upper or mixed case names then the name specified in the "USE" directive must match the case exactly.

The "USE" directive is used to create plugin objects and does so by calling the plugin() method on the current Template::Context object. If the plugin name is defined in the "PLUGINS" hash then the corresponding Perl module is loaded via "require()". The context then calls the load() class method which should return the class name (default and general case) or a prototype object against which the new() method can be called to instantiate individual plugin objects.

If the plugin name is not defined in the "PLUGINS" hash then the "PLUGIN_BASE" and/or "LOAD_PERL" options come into effect.

PLUGIN_BASE

The "PLUGIN_BASE" can be specified as a reference to an array of module namespaces, or as a single value which is automatically converted to a list. The default "PLUGIN_BASE" value ("Template::Plugin") is then added to the end of this list.

example 1:

    my $template = Template->new({
        PLUGIN_BASE => 'MyOrg::Template::Plugin',
    });

    [% USE Foo %]    # => MyOrg::Template::Plugin::Foo
                       or        Template::Plugin::Foo

example 2:

    my $template = Template->new({
        PLUGIN_BASE => [   'MyOrg::Template::Plugin',
                           'YourOrg::Template::Plugin'  ],
    });

template:

    [% USE Foo %]    # =>   MyOrg::Template::Plugin::Foo
                       or YourOrg::Template::Plugin::Foo
                       or          Template::Plugin::Foo

If you don't want the default "Template::Plugin" namespace added to the end of the "PLUGIN_BASE", then set the $Template::Plugins::PLUGIN_BASE variable to a false value before calling the new() Template#new() constructor method. This is shown in the example below where the "Foo" plugin is located as "My::Plugin::Foo" or "Your::Plugin::Foo" but not as "Template::Plugin::Foo".

example 3:

    use Template::Plugins;
    $Template::Plugins::PLUGIN_BASE = '';

    my $template = Template->new({
        PLUGIN_BASE => [   'My::Plugin',
                           'Your::Plugin'  ],
    });

template:

    [% USE Foo %]    # =>   My::Plugin::Foo
                       or Your::Plugin::Foo

LOAD_PERL

By default, the "LOAD_PERL" option is set to 0 and no attempt will be made to load any Perl modules that aren't named explicitly in the "PLUGINS" hash or reside in a package as named by one of the "PLUGIN_BASE" components.

Plugins loaded using the "PLUGINS" or "PLUGIN_BASE" receive a reference to the current context object as the first argument to the new() constructor. Modules loaded using "LOAD_PERL" are assumed to not conform to the plugin interface. They must provide a "new()" class method for instantiating objects but it will not receive a reference to the context as the first argument.

Plugin modules should provide a load() class method (or inherit the default one from the Template::Plugin base class) which is called the first time the plugin is loaded. Regular Perl modules need not. In all other respects, regular Perl objects and Template Toolkit plugins are identical.

If a particular Perl module does not conform to the common, but not unilateral, "new()" constructor convention then a simple plugin wrapper can be written to interface to it.

FILTERS

The "FILTERS" option should be specified as a reference to a hash array in which each key represents the name of a filter. The corresponding value should contain a reference to an array containing a subroutine reference and a flag which indicates if the filter is static (0) or dynamic (1). A filter may also be specified as a solitary subroutine reference and is assumed to be static.

    $template = Template->new({
        FILTERS => {
            'sfilt1' =>   \&static_filter,      # static
            'sfilt2' => [ \&static_filter, 0 ], # same as above
            'dfilt1' => [ \&dyanamic_filter_factory, 1 ],
        },
    });

Additional filters can be specified at any time by calling the define_filter() method on the current Template::Context object. The method accepts a filter name, a reference to a filter subroutine and an optional flag to indicate if the filter is dynamic.

    my $context = $template->context();
    $context->define_filter('new_html', \&new_html);
    $context->define_filter('new_repeat', \&new_repeat, 1);

Static filters are those where a single subroutine reference is used for all invocations of a particular filter. Filters that don't accept any configuration parameters (e.g. "html") can be implemented statically. The subroutine reference is simply returned when that particular filter is requested. The subroutine is called to filter the output of a template block which is passed as the only argument. The subroutine should return the modified text.

    sub static_filter {
        my $text = shift;
        # do something to modify $text...
        return $text;
    }

The following template fragment:

    [% FILTER sfilt1 %]
    Blah blah blah.
    [% END %]

is approximately equivalent to:

    &static_filter("\nBlah blah blah.\n");

Filters that can accept parameters (e.g. "truncate") should be implemented dynamically. In this case, the subroutine is taken to be a filter 'factory' that is called to create a unique filter subroutine each time one is requested. A reference to the current Template::Context object is passed as the first parameter, followed by any additional parameters specified. The subroutine should return another subroutine reference (usually a closure) which implements the filter.

    sub dynamic_filter_factory {
        my ($context, @args) = @_;

        return sub {
            my $text = shift;
            # do something to modify $text...
            return $text;
        }
    }

The following template fragment:

    [% FILTER dfilt1(123, 456) %]
    Blah blah blah
    [% END %]

is approximately equivalent to:

    my $filter = &dynamic_filter_factory($context, 123, 456);
    &$filter("\nBlah blah blah.\n");

See the "FILTER" directive for further examples.

LOAD_TEMPLATES

    my $template = Template->new({
        LOAD_TEMPLATES => [
            MyOrg::Template::Provider->new({ ... }),
            Template::Provider->new({ ... }),
        ],
    });

When a "PROCESS", "INCLUDE" or "WRAPPER" directive is encountered, the named template may refer to a locally defined "BLOCK" or a file relative to the "INCLUDE_PATH" (or an absolute or relative path if the appropriate "ABSOLUTE" or "RELATIVE" options are set). If a "BLOCK" definition can't be found (see the Template::Context template() method for a discussion of "BLOCK" locality) then each of the "LOAD_TEMPLATES" provider objects is queried in turn via the fetch() method to see if it can supply the required template.

Each provider can return a compiled template, an error, or decline to service the request in which case the responsibility is passed to the next provider. If none of the providers can service the request then a 'not found' error is returned. The same basic provider mechanism is also used for the "INSERT" directive but it bypasses any "BLOCK" definitions and doesn't attempt is to parse or process the contents of the template file.

If "LOAD_TEMPLATES" is undefined, a single default provider will be instantiated using the current configuration parameters. For example, the Template::Provider "INCLUDE_PATH" option can be specified in the Template configuration and will be correctly passed to the provider's constructor method.

    my $template = Template->new({
        INCLUDE_PATH => '/here:/there',
    });

LOAD_PLUGINS

    my $template = Template->new({
        LOAD_PLUGINS => [
            MyOrg::Template::Plugins->new({ ... }),
            Template::Plugins->new({ ... }),
        ],
    });

By default, a single Template::Plugins object is created using the current configuration hash. Configuration items destined for the Template::Plugins constructor may be added to the Template constructor.

    my $template = Template->new({
        PLUGIN_BASE => 'MyOrg::Template::Plugins',
        LOAD_PERL   => 1,
    });

LOAD_FILTERS

    my $template = Template->new({
        LOAD_FILTERS => [
            MyTemplate::Filters->new(),
            Template::Filters->new(),
        ],
    });

By default, a single Template::Filters object is created for the "LOAD_FILTERS" list.

TOLERANT

When the "TOLERANT" flag is set to any true values, errors will be silently ignored and the provider will instead return "STATUS_DECLINED". This allows a subsequent provider to take responsibility for providing the resource, rather than failing the request outright. If all providers decline to service the request, either through tolerated failure or a genuine disinclination to comply, then a '"<resource> not found"' exception is raised.

SERVICE

    my $template = Template->new({
        SERVICE => MyOrg::Template::Service->new({ ... }),
    });

CONTEXT

    my $template = Template->new({
        CONTEXT => MyOrg::Template::Context->new({ ... }),
    });

STASH

    my $stash = MyOrg::Template::Stash->new({ ... });
    my $template = Template->new({
        STASH => $stash,
    });

If unspecified, a default stash object is created using the "VARIABLES" configuration item to initialise the stash variables.

    my $template = Template->new({
        VARIABLES => {
            id    => 'abw',
            name  => 'Andy Wardley',
        },
    };

PARSER

    my $template = Template->new({
        PARSER => MyOrg::Template::Parser->new({ ... }),
    });

GRAMMAR

Source templates are compiled to Perl code by the Template::Parser using the Template::Grammar (by default) to define the language structure and semantics. Compiled templates are thus inherently "compatible" with each other and there is nothing to prevent any number of different template languages being compiled and used within the same Template Toolkit processing environment (other than the usual time and memory constraints).

The Template::Grammar file is constructed from a YACC like grammar (using "Parse::YAPP") and a skeleton module template. These files are provided, along with a small script to rebuild the grammar, in the parser sub-directory of the distribution.

You don't have to know or worry about these unless you want to hack on the template language or define your own variant. There is a README file in the same directory which provides some small guidance but it is assumed that you know what you're doing if you venture herein. If you grok LALR parsers, then you should find it comfortably familiar.

By default, an instance of the default Template::Grammar will be created and used automatically if a "GRAMMAR" item isn't specified.

    use MyOrg::Template::Grammar;

    my $template = Template->new({
        GRAMMAR = MyOrg::Template::Grammar->new();
    });