Template::Cache - object for loading, compiling and caching template documents
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); $cache->load($input); $cache->compile($text);
This documentation describes the Template::Cache module and is aimed at people who wish to understand, extend or build template processing applications with the Template Toolkit.
For a general overview and information of how to use the modules, write and render templates, see Template-Toolkit.
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, });
Constructor method which instantiates a new Template::Cache object. A hash reference may be passed containing the following configuration items:
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.
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 }, ], });
The INCLUDE_PATH values above may denote several directories separated by a colon character ':'. On some operating systems, the colon may be legally embedded in a directory (e.g. 'C:\DOS98'). The PATH_SEPARATOR can be used to specify an alternative delimiter.
use Template::Cache; my $cache = Template::Cache->new({ INCLUDE_PATH => 'C:\\TMP | D:\\FOO', PATH_SEPARATOR => ' | ', });
The default directory separator is the forward slash '/' character. The DIR_SEPARATOR can be used to specify an alternate character sequence. Paths specified in template files with forwards slashes will be converted to the correct format by the fetch() method.
# note the need to escape all those backslashes my $cache = Template::Cache->new({ INCLUDE_PATH => 'D:\\ABW\\TEMPLATES + C:\\USR\\LOCAL\\TEMPLATES', PATH_SEPARATOR => ' + ', DIR_SEPARATOR => '\\', }); my $template = $cache->fetch('foo/bar');
The fetch() method shown above will look for the following files:
D:\ABW\TEMPLATES\foo\bar C:\USR\LOCAL\TEMPLATES\foo\bar
Similarly, specifying the following in a template file will have the same effect. This allows template authors to use a consistent file naming convention within templates (i.e. always use forwards slashes) and have the cache loader convert it to the correct local equivalent.
%% INCLUDE foo/bar %%
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.
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.
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') }
Method called by fetch() to find and load a template document and then call compile() to parse and compile the template. The $template parameter should contain a filename or be a reference as described in fetch() above.
$compiled = $cache->load($inputsrc);
Method called by load() to compile the template text. Delegates to a Template::Parser object.
$compiled = $cache->compile($text);
Returns the current error condition which is represented as a Template::Exception object.
Andy Wardley <cre.canon.co.uk>
$Revision: 1.5 $
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.
Template-Toolkit
To install Template, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Template
CPAN shell
perl -MCPAN -e shell install Template
For more information on module installation, please visit the detailed CPAN module installation guide.