NAME

Template::Cache - object for loading, compiling and caching template documents

SYNOPSIS

    use Template::Cache;

    $cache    = Template::Cache->new({ 
                    INCLUDE_PATH = \@search_path,
                });

    $template = $cache->fetch($filename);
    $template = $cache->fetch($filehandle, $name);
    $template = $cache->fetch(\$text, $name);

    warn $cache->error()
        unless $template;

    $cache->store($template, $name);

DESCRIPTION

The Template::Cache module defines an object class which is used to find, load, compile and cache template document files. A Template::Cache object is created by, or supplied as a configuration item to a Template::Context which calls its fetch() method to request templates as they are required.

The cache can load templates from files specified either by filename or by passing a file handle or GLOB reference (e.g. \*STDIN) to the fetch() method. A reference to a text string containing the template text may also be passed to fetch(). This method returns a cache version of the template document if it exists or calls _load() to load and compile the template. Compiled templates are then cached by their filename or a specific alias which can be passed as a second parameter to fetch(). A template whose source is a file handle, glob or text reference (i.e. the first parameter is any kind of reference) will not be cached unless an alias is specifically provided.

The _load() method takes the input source (filename, file handle, text ref, etc.) as its only parameter and attempts to read the content. If a filename has been specified then the method will look in each directory specified in the PATH configuration option to find the file. If the PATH has not been specified then the current directory only is searched.

Once loaded, the template text is passed to _compile() which delegates the task of parsing and compiling the document to a Template::Parser object. The PARSER configuration option may be specified to provide a reference to a Template::Parser, or subclass thereof, which should be used instead. See Template::Parser for further information.

In some environments it is desirable to share a template cache among multiple template processors. In an Apache/mod_perl server, for example, one may have different template processors rendering different parts of a web site but sharing the same template repository. This can be acheived by explicitly supplying a reference to a Template::Cache as the CACHE configuration item passed to the Template constructor, new(). This is then passed to the Template::Context constructor.

    use Template;

    my $cache = Template::Cache->new({ 
        INCLUDE_PATH => '/user/abw/templates:/usr/local/templates',
    });

    my $tp1 = Template->new({
        CACHE => $cache,
    });

    my $tp2 = Template->new({
        CACHE => $cache,
    });

PUBLIC METHODS

new(\%config)

Constructor method which instantiates a new Template::Cache object. A hash reference may be passed containing the following configuration items:

CACHE

The CACHE option specifies to default behaviour for the cache: whether to cache compiled documents or not. A value of 1 (CACHE_ALL) will cause all compiled templates to be cached. A value of 0 (CACHE_NONE) will cause none of them to be cached and re-parsed on demand. The default is CACHE_ALL.

The Template::Constants provides a ':cache' export tagset which imports the definitions for CACHE_ALL and CACHE_NONE. Other caching strategies may be support in the future.

The CACHE option can also be applied on a per-directory basis, as shown below.

INCLUDE_PATH

The INCLUDE_PATH option specifies one or directories in which to look for template files. Multiple directories can be delimited by a ':' (or the value of the PATH_SEPARATOR) or specified as a reference to a list.

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

    my $cache = Template::Cache->new({
        INCLUDE_PATH => [ '/usr/local/templates', '/usr/web/templates' ],
    });

Each directory entry may be followed by a hash array reference containing caching options specific to those directories.

    use Template::Cache;
    use Template::Constants qw( :cache );

    my $tcache = Template::Cache->new({
        INCLUDE_PATH => [ 
            # CACHE_ALL files (default) in these directories
            '/user/web/elements:/usr/local/web/elements'
            # CACHE_NONE of the files from this directory
            '/user/web/templates' => { CACHE => CACHE_NONE },

        ],
    });

PARSER

A reference to a Template::Parser object, or sub-class thereof, which should be used for parsing and compiling templates as they are loaded. A default Template::Parser object when first used if this option is not specified.

fetch($template, $alias)

This method is called to load, parse and compile template documents. The first parameter should contain the name of a template file relative to one of the PATH directories, or in the current directory if PATH wasn't specified. Alternatively, $template may be a reference to a SCALAR variable containing the template text, or a reference to a file handle (e.g. IO::Handle et al) or GLOB from which the template content should be read.

The compiled template is then cached internally using the template file name or another alias specified as the second parameter. If $template is a reference then it will only be cached if an $alias is provided. The template will not be cache if $alias is set to 0.

Future calls to fetch() where $template matches a cached entry will return the compiled template without re-compiling it.

    $t = $cache->fetch('myfile');       # compiles template
    $t = $cache->fetch('myfile');       # returns cached version
    $t = $cache->fetch($filehandle);    # read file - don't cache
    $t = $cache->fetch(\*DATA, 'foo');  # read file, cache as 'foo'
    $t = $cache->fetch('foo');          # return cached 'foo'

Calling fetch() with a non-zero alias will always cause the entry to be cached under that name. If $template represents an existing template in the cache then it will cached under the new $alias as well as the original cache name.

store($template, $alias)

Allows a pre-compiled template block ($template) to be added to the cache under a given name ($alias).

    if ($compiled = $cache->compile($mytext)) {
        $cache->store($compiled, 'my_compiled_template')
    }

error()

Returns the current error condition which is represented as a Template::Exception object.

AUTHOR

Andy Wardley <cre.canon.co.uk>

REVISION

$Revision: 1.11 $

COPYRIGHT

Copyright (C) 1996-1999 Andy Wardley. All Rights Reserved. Copyright (C) 1998-1999 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

Template

cpanm Template

perl -MCPAN -e shell
install Template