NAME

Template::Multipass - Add a meta template pass to TT

SYNOPSIS

my $t = Template::Multipass->new(
    INCLUDE_PATH => [ file(__FILE__)->parent->subdir("templates")->stringify ],
    COMPILE_EXT  => "c",
    MULTIPASS => {
        VARS => {
            lang => "en",
            loc => sub { $lang_handle->maketext(@_) },
        }
    },
);

$t->process( ... );


# ORIGINAL TT

[% loc("hello") %] [% user.name %],
[% loc("instructions") %]


# MULTIPASS TEMPLATE

{% loc("hello") %} [% user.name %],
{% loc("instructions") %}


# RESULTING CACHED TEMPLATE

Hello, [% user.name %]
Please select a Moose

DESCRIPTION

This module was written to precompute the static parts of templates (text based on variables which are not runtime dependant, and can thus be precomputed).

The most prominent example of this is localization of constant strings. This is demonstrated in the "SYNOPSIS".

Template::Multipass will first process the template with only the meta variables, and cache the result. Then it will process the file again with all of the variables. Subsequent runs will not have to recompute the meta var run unless the variables have been changed.

CONFIGURATION

The configuration values inside MULTIPASS in the top level config will be overlayed on top of the normal config during meta template processing. This works for values such as START_TAG and END_TAG (which default to {% and %}), and may work for other values.

Additionallly the MULTIPASS hash can take a VARS hash to be used as the meta vars in all runs.

This var hash can be further added by passing them as an option to process:

$t->process( $template, $vars, $output, { meta_vars => { ... more vars ... } } );

Values in options will override those in the configuration.

Lastly the MANGLE_METHOD and MANGLE_HASH_VARS values may also be set in the MULTIPASS configuration, and will be discussed in "CACHING".

METHODS

See Template. The API is unchanged except for:

process

Also accepts the meta_vars option.

CAVEAT

Wrappers

Wrappers processed at meta time ({% WRAPPER blah %}...{% END %}) will require the use of {% %} tags to embed the content. Otherwise the content is lost till the [% %] run starts.

CACHING

Caching is done using the native Template caching mechanism (COMPILE_EXT, etc).

See "Caching_and_Compiling_Options" in Template.

The only difference is that meta templates are cached using filenames that incorperate their meta vars.

There are two methods to mangle the file name, using a recursive MD5 hash of the variable hash, or just the top level non reference ones (the default). This is controlled using MANGLE_HASH_VARS.

In order to properly utilize the default method to ease debugging (clearer file names) pass in simple top level values. For example if you have a loc function or a lang_handle var to run Locale::Maketext localization, also add a lang top level var containing the language code. The resulting file name will be lang-$lang,$template_name.ttc.

If your meta templates require caching based on values inside references or you'd rather not bother with creating top level strings simply enable MANGLE_HASH_VARS, which will result in a file name like 8a1fad1d1f3313b3647ac90b29eaac95-$template_name.ttc.

INTERNALS OVERVIEW

The way this module works is by wrapping all the providers in a normally instantiated Template object with Template::Multipass::Provider. This provider will delegate to it's wrapped provider and then call back to the top level object for meta template processing. It'll then cache the result with the mangled name, and return the output of the template run as the input of the original template.