1Template::Provider(3) User Contributed Perl DocumentationTemplate::Provider(3)
2
6 Template::Provider - Provider module for loading/compiling templates
7
9 $provider = Template::Provider->new(\%options);
10 ($template, $error) = $provider->fetch($name);
12
14 The Template::Provider is used to load, parse, compile and cache tem‐
15 plate documents. This object may be sub-classed to provide more spe‐
16 cific facilities for loading, or otherwise providing access to tem‐
17 plates.
18 The Template::Context objects maintain a list of Template::Provider
20 objects which are polled in turn (via fetch()) to return a requested
21 template. Each may return a compiled template, raise an error, or
22 decline to serve the reqest, giving subsequent providers a chance to do
23 so.
24 This is the "Chain of Responsiblity" pattern. See 'Design Patterns'
26 for further information.
27 This documentation needs work.
29
31 new(\%options)
32 Constructor method which instantiates and returns a new Tem‐
34 plate::Provider object. The optional parameter may be a hash reference
35 containing any of the following items:
36 INCLUDE_PATH
38 The INCLUDE_PATH is used to specify one or more directories in
39 which template files are located. When a template is requested
40 that isn't defined locally as a BLOCK, each of the INCLUDE_PATH
41 directories is searched in turn to locate the template file. Mul‐
42 tiple directories can be specified as a reference to a list or as a
43 single string where each directory is delimited by ':'.
44 my $provider = Template::Provider->new({
46 INCLUDE_PATH => '/usr/local/templates',
47 });
48 my $provider = Template::Provider->new({
50 INCLUDE_PATH => '/usr/local/templates:/tmp/my/templates',
51 });
52 my $provider = Template::Provider->new({
54 INCLUDE_PATH => [ '/usr/local/templates',
55 '/tmp/my/templates' ],
56 });
57 On Win32 systems, a little extra magic is invoked, ignoring delim‐
59 iters that have ':' followed by a '/' or '\'. This avoids confu‐
60 sion when using directory names like 'C:\Blah Blah'.
61 When specified as a list, the INCLUDE_PATH path can contain ele‐
63 ments which dynamically generate a list of INCLUDE_PATH directo‐
64 ries. These generator elements can be specified as a reference to
65 a subroutine or an object which implements a paths() method.
66 my $provider = Template::Provider->new({
68 INCLUDE_PATH => [ '/usr/local/templates',
69 \&incpath_generator,
70 My::IncPath::Generator->new( ... ) ],
71 });
72 Each time a template is requested and the INCLUDE_PATH examined,
74 the subroutine or object method will be called. A reference to a
75 list of directories should be returned. Generator subroutines
76 should report errors using die(). Generator objects should return
77 undef and make an error available via its error() method.
78 For example:
80 sub incpath_generator {
82 # ...some code...
84 if ($all_is_well) {
86 return \@list_of_directories;
87 }
88 else {
89 die "cannot generate INCLUDE_PATH...\n";
90 }
91 }
92 or:
94 package My::IncPath::Generator;
96 # Template::Base (or Class::Base) provides error() method
98 use Template::Base;
99 use base qw( Template::Base );
100 sub paths {
102 my $self = shift;
103 # ...some code...
105 if ($all_is_well) {
107 return \@list_of_directories;
108 }
109 else {
110 return $self->error("cannot generate INCLUDE_PATH...\n");
111 }
112 }
113 1;
115 DELIMITER
117 Used to provide an alternative delimiter character sequence for
118 separating paths specified in the INCLUDE_PATH. The default value
119 for DELIMITER is ':'.
120 # tolerate Silly Billy's file system conventions
122 my $provider = Template::Provider->new({
123 DELIMITER => '; ',
124 INCLUDE_PATH => 'C:/HERE/NOW; D:/THERE/THEN',
125 });
126 # better solution: install Linux! :-)
128 On Win32 systems, the default delimiter is a little more intelli‐
130 gent, splitting paths only on ':' characters that aren't followed
131 by a '/'. This means that the following should work as planned,
132 splitting the INCLUDE_PATH into 2 separate directories, C:/foo and
133 C:/bar.
134 # on Win32 only
136 my $provider = Template::Provider->new({
137 INCLUDE_PATH => 'C:/Foo:C:/Bar'
138 });
139 However, if you're using Win32 then it's recommended that you
141 explicitly set the DELIMITER character to something else (e.g. ';')
142 rather than rely on this subtle magic.
143 ABSOLUTE
145 The ABSOLUTE flag is used to indicate if templates specified with
146 absolute filenames (e.g. '/foo/bar') should be processed. It is
147 disabled by default and any attempt to load a template by such a
148 name will cause a 'file' exception to be raised.
149 my $provider = Template::Provider->new({
151 ABSOLUTE => 1,
152 });
153 # this is why it's disabled by default
155 [% INSERT /etc/passwd %]
156 On Win32 systems, the regular expression for matching absolute
158 pathnames is tweaked slightly to also detect filenames that start
159 with a driver letter and colon, such as:
160 C:/Foo/Bar
162 RELATIVE
164 The RELATIVE flag is used to indicate if templates specified with
165 filenames relative to the current directory (e.g. './foo/bar' or
166 '../../some/where/else') should be loaded. It is also disabled by
167 default, and will raise a 'file' error if such template names are
168 encountered.
169 my $provider = Template::Provider->new({
171 RELATIVE => 1,
172 });
173 [% INCLUDE ../logs/error.log %]
175 DEFAULT
177 The DEFAULT option can be used to specify a default template which
178 should be used whenever a specified template can't be found in the
179 INCLUDE_PATH.
180 my $provider = Template::Provider->new({
182 DEFAULT => 'notfound.html',
183 });
184 If a non-existant template is requested through the Template
186 process() method, or by an INCLUDE, PROCESS or WRAPPER directive,
187 then the DEFAULT template will instead be processed, if defined.
188 Note that the DEFAULT template is not used when templates are spec‐
189 ified with absolute or relative filenames, or as a reference to a
190 input file handle or text string.
191 CACHE_SIZE
193 The Template::Provider module caches compiled templates to avoid
194 the need to re-parse template files or blocks each time they are
195 used. The CACHE_SIZE option is used to limit the number of com‐
196 piled templates that the module should cache.
197 By default, the CACHE_SIZE is undefined and all compiled templates
199 are cached. When set to any positive value, the cache will be lim‐
200 ited to storing no more than that number of compiled templates.
201 When a new template is loaded and compiled and the cache is full
202 (i.e. the number of entries == CACHE_SIZE), the least recently used
203 compiled template is discarded to make room for the new one.
204 The CACHE_SIZE can be set to 0 to disable caching altogether.
206 my $provider = Template::Provider->new({
208 CACHE_SIZE => 64, # only cache 64 compiled templates
209 });
210 my $provider = Template::Provider->new({
212 CACHE_SIZE => 0, # don't cache any compiled templates
213 });
214 COMPILE_EXT
216 From version 2 onwards, the Template Toolkit has the ability to
217 compile templates to Perl code and save them to disk for subsequent
218 use (i.e. cache persistence). The COMPILE_EXT option may be pro‐
219 vided to specify a filename extension for compiled template files.
220 It is undefined by default and no attempt will be made to read or
221 write any compiled template files.
222 my $provider = Template::Provider->new({
224 COMPILE_EXT => '.ttc',
225 });
226 If COMPILE_EXT is defined (and COMPILE_DIR isn't, see below) then
228 compiled template files with the COMPILE_EXT extension will be
229 written to the same directory from which the source template files
230 were loaded.
231 Compiling and subsequent reuse of templates happens automatically
233 whenever the COMPILE_EXT or COMPILE_DIR options are set. The Tem‐
234 plate Toolkit will automatically reload and reuse compiled files
235 when it finds them on disk. If the corresponding source file has
236 been modified since the compiled version as written, then it will
237 load and re-compile the source and write a new compiled version to
238 disk.
239 This form of cache persistence offers significant benefits in terms
241 of time and resources required to reload templates. Compiled tem‐
242 plates can be reloaded by a simple call to Perl's require(), leav‐
243 ing Perl to handle all the parsing and compilation. This is a Good
244 Thing.
245 COMPILE_DIR
247 The COMPILE_DIR option is used to specify an alternate directory
248 root under which compiled template files should be saved.
249 my $provider = Template::Provider->new({
251 COMPILE_DIR => '/tmp/ttc',
252 });
253 The COMPILE_EXT option may also be specified to have a consistent
255 file extension added to these files.
256 my $provider1 = Template::Provider->new({
258 COMPILE_DIR => '/tmp/ttc',
259 COMPILE_EXT => '.ttc1',
260 });
261 my $provider2 = Template::Provider->new({
263 COMPILE_DIR => '/tmp/ttc',
264 COMPILE_EXT => '.ttc2',
265 });
266 When COMPILE_EXT is undefined, the compiled template files have the
268 same name as the original template files, but reside in a different
269 directory tree.
270 Each directory in the INCLUDE_PATH is replicated in full beneath
272 the COMPILE_DIR directory. This example:
273 my $provider = Template::Provider->new({
275 COMPILE_DIR => '/tmp/ttc',
276 INCLUDE_PATH => '/home/abw/templates:/usr/share/templates',
277 });
278 would create the following directory structure:
280 /tmp/ttc/home/abw/templates/
282 /tmp/ttc/usr/share/templates/
283 Files loaded from different INCLUDE_PATH directories will have
285 their compiled forms save in the relevant COMPILE_DIR directory.
286 On Win32 platforms a filename may by prefixed by a drive letter and
288 colon. e.g.
289 C:/My Templates/header
291 The colon will be silently stripped from the filename when it is
293 added to the COMPILE_DIR value(s) to prevent illegal filename being
294 generated. Any colon in COMPILE_DIR elements will be left intact.
295 For example:
296 # Win32 only
298 my $provider = Template::Provider->new({
299 DELIMITER => ';',
300 COMPILE_DIR => 'C:/TT2/Cache',
301 INCLUDE_PATH => 'C:/TT2/Templates;D:/My Templates',
302 });
303 This would create the following cache directories:
305 C:/TT2/Cache/C/TT2/Templates
307 C:/TT2/Cache/D/My Templates
308 TOLERANT
310 The TOLERANT flag is used by the various Template Toolkit provider
311 modules (Template::Provider, Template::Plugins, Template::Filters)
312 to control their behaviour when errors are encountered. By
313 default, any errors are reported as such, with the request for the
314 particular resource (template, plugin, filter) being denied and an
315 exception raised. When the TOLERANT flag is set to any true val‐
316 ues, errors will be silently ignored and the provider will instead
317 return STATUS_DECLINED. This allows a subsequent provider to take
318 responsibility for providing the resource, rather than failing the
319 request outright. If all providers decline to service the request,
320 either through tolerated failure or a genuine disinclination to
321 comply, then a '<resource> not found' exception is raised.
322 PARSER
324 The Template::Parser module implements a parser object for compil‐
325 ing templates into Perl code which can then be executed. A default
326 object of this class is created automatically and then used by the
327 Template::Provider whenever a template is loaded and requires com‐
328 pilation. The PARSER option can be used to provide a reference to
329 an alternate parser object.
330 my $provider = Template::Provider->new({
332 PARSER => MyOrg::Template::Parser->new({ ... }),
333 });
334 DEBUG
336 The DEBUG option can be used to enable debugging messages from the
337 Template::Provider module by setting it to include the
338 DEBUG_PROVIDER value.
339 use Template::Constants qw( :debug );
341 my $template = Template->new({
343 DEBUG => DEBUG_PROVIDER,
344 });
345 fetch($name)
347 Returns a compiled template for the name specified. If the template
349 cannot be found then (undef, STATUS_DECLINED) is returned. If an error
350 occurs (e.g. read error, parse error) then ($error, STATUS_ERROR) is
351 returned, where $error is the error message generated. If the TOLERANT
352 flag is set the the method returns (undef, STATUS_DECLINED) instead of
353 returning an error.
354 store($name, $template)
356 Stores the compiled template, $template, in the cache under the name,
358 $name. Susbequent calls to fetch($name) will return this template in
359 preference to any disk-based file.
360 include_path(\@newpath))
362 Accessor method for the INCLUDE_PATH setting. If called with an argu‐
364 ment, this method will replace the existing INCLUDE_PATH with the new
365 value.
366 paths()
368 This method generates a copy of the INCLUDE_PATH list. Any elements in
370 the list which are dynamic generators (e.g. references to subroutines
371 or objects implementing a paths() method) will be called and the list
372 of directories returned merged into the output list.
373 It is possible to provide a generator which returns itself, thus send‐
375 ing this method into an infinite loop. To detect and prevent this from
376 happening, the $MAX_DIRS package variable, set to 64 by default, limits
377 the maximum number of paths that can be added to, or generated for the
378 output list. If this number is exceeded then the method will immedi‐
379 ately return an error reporting as much.
380
382 Andy Wardley <abw@wardley.org>
383 <http://wardley.org/⎪http://wardley.org/>
385
387 2.91, distributed as part of the Template Toolkit version 2.18,
388 released on 09 February 2007.
389
391 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
392 This module is free software; you can redistribute it and/or modify it
394 under the same terms as Perl itself.
395
397 Template, Template::Parser, Template::Context
398perl v5.8.8 2007-02-09 Template::Provider(3)