Template::Provider(3pm)

1Template::Provider(3) User Contributed Perl DocumentationTemplate::Provider(3)
2
3
4

NAME

6       Template::Provider - Provider module for loading/compiling templates
7

SYNOPSIS

9           $provider = Template::Provider->new(\%options);
10
11           ($template, $error) = $provider->fetch($name);
12

DESCRIPTION

14       The Template::Provider is used to load, parse, compile and cache
15       template documents. This object may be sub-classed to provide more
16       specific facilities for loading, or otherwise providing access to
17       templates.
18
19       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 request, giving subsequent providers a chance to
23       do so.
24
25       The Template::Provider can also be subclassed to provide templates from
26       a different source, e.g. a database. See SUBCLASSING below.
27
28       This documentation needs work.
29

PUBLIC METHODS

31   new(\%options)
32       Constructor method which instantiates and returns a new
33       "Template::Provider" object.  A reference to a hash array of
34       configuration options may be passed.
35
36       See "CONFIGURATION OPTIONS" below for a summary of configuration
37       options and Template::Manual::Config for full details.
38
39   fetch($name)
40       Returns a compiled template for the name specified. If the template
41       cannot be found then "(undef, STATUS_DECLINED)" is returned. If an
42       error occurs (e.g.  read error, parse error) then "($error,
43       STATUS_ERROR)" is returned, where $error is the error message
44       generated. If the TOLERANT option is set the the method returns
45       "(undef, STATUS_DECLINED)" instead of returning an error.
46
47   store($name, $template)
48       Stores the compiled template, $template, in the cache under the name,
49       $name.  Susbequent calls to "fetch($name)" will return this template in
50       preference to any disk-based file.
51
52   include_path(\@newpath)
53       Accessor method for the "INCLUDE_PATH" setting.  If called with an
54       argument, this method will replace the existing "INCLUDE_PATH" with the
55       new value.
56
57   paths()
58       This method generates a copy of the "INCLUDE_PATH" list.  Any elements
59       in the list which are dynamic generators (e.g. references to
60       subroutines or objects implementing a "paths()" method) will be called
61       and the list of directories returned merged into the output list.
62
63       It is possible to provide a generator which returns itself, thus
64       sending this method into an infinite loop.  To detect and prevent this
65       from happening, the $MAX_DIRS package variable, set to 64 by default,
66       limits the maximum number of paths that can be added to, or generated
67       for the output list.  If this number is exceeded then the method will
68       immediately return an error reporting as much.
69

CONFIGURATION OPTIONS

71       The following list summarises the configuration options that can be
72       provided to the "Template::Provider" new() constructor. Please consult
73       Template::Manual::Config for further details and examples of each
74       configuration option in use.
75
76   INCLUDE_PATH
77       The INCLUDE_PATH option is used to specify one or more directories in
78       which template files are located.
79
80           # single path
81           my $provider = Template::Provider->new({
82               INCLUDE_PATH => '/usr/local/templates',
83           });
84
85           # multiple paths
86           my $provider = Template::Provider->new({
87               INCLUDE_PATH => [ '/usr/local/templates',
88                                 '/tmp/my/templates' ],
89           });
90
91   ABSOLUTE
92       The ABSOLUTE flag is used to indicate if templates specified with
93       absolute filenames (e.g. '"/foo/bar"') should be processed. It is
94       disabled by default and any attempt to load a template by such a name
95       will cause a '"file"' exception to be raised.
96
97           my $provider = Template::Provider->new({
98               ABSOLUTE => 1,
99           });
100
101   RELATIVE
102       The RELATIVE flag is used to indicate if templates specified with
103       filenames relative to the current directory (e.g.  "./foo/bar" or
104       "../../some/where/else") should be loaded. It is also disabled by
105       default, and will raise a "file" error if such template names are
106       encountered.
107
108           my $provider = Template::Provider->new({
109               RELATIVE => 1,
110           });
111
112   DEFAULT
113       The DEFAULT option can be used to specify a default template which
114       should be used whenever a specified template can't be found in the
115       INCLUDE_PATH.
116
117           my $provider = Template::Provider->new({
118               DEFAULT => 'notfound.html',
119           });
120
121       If a non-existant template is requested through the Template process()
122       method, or by an "INCLUDE", "PROCESS" or "WRAPPER" directive, then the
123       "DEFAULT" template will instead be processed, if defined. Note that the
124       "DEFAULT" template is not used when templates are specified with
125       absolute or relative filenames, or as a reference to a input file
126       handle or text string.
127
128   ENCODING
129       The Template Toolkit will automatically decode Unicode templates that
130       have a Byte Order Marker (BOM) at the start of the file.  This option
131       can be used to set the default encoding for templates that don't define
132       a BOM.
133
134           my $provider = Template::Provider->new({
135               ENCODING => 'utf8',
136           });
137
138       See Encode for further information.
139
140   CACHE_SIZE
141       The CACHE_SIZE option can be used to limit the number of compiled
142       templates that the module should cache. By default, the CACHE_SIZE is
143       undefined and all compiled templates are cached.
144
145           my $provider = Template::Provider->new({
146               CACHE_SIZE => 64,   # only cache 64 compiled templates
147           });
148
149   STAT_TTL
150       The STAT_TTL value can be set to control how long the
151       "Template::Provider" will keep a template cached in memory before
152       checking to see if the source template has changed.
153
154           my $provider = Template::Provider->new({
155               STAT_TTL => 60,  # one minute
156           });
157
158   COMPILE_EXT
159       The COMPILE_EXT option can be provided to specify a filename extension
160       for compiled template files.  It is undefined by default and no attempt
161       will be made to read or write any compiled template files.
162
163           my $provider = Template::Provider->new({
164               COMPILE_EXT => '.ttc',
165           });
166
167   COMPILE_DIR
168       The COMPILE_DIR option is used to specify an alternate directory root
169       under which compiled template files should be saved.
170
171           my $provider = Template::Provider->new({
172               COMPILE_DIR => '/tmp/ttc',
173           });
174
175   TOLERANT
176       The TOLERANT flag can be set to indicate that the "Template::Provider"
177       module should ignore any errors encountered while loading a template
178       and instead return "STATUS_DECLINED".
179
180   PARSER
181       The PARSER option can be used to define a parser module other than the
182       default of Template::Parser.
183
184           my $provider = Template::Provider->new({
185               PARSER => MyOrg::Template::Parser->new({ ... }),
186           });
187
188   DEBUG
189       The DEBUG option can be used to enable debugging messages from the
190       Template::Provider module by setting it to include the "DEBUG_PROVIDER"
191       value.
192
193           use Template::Constants qw( :debug );
194
195           my $template = Template->new({
196               DEBUG => DEBUG_PROVIDER,
197           });
198

SUBCLASSING

200       The "Template::Provider" module can be subclassed to provide templates
201       from a different source (e.g. a database).  In most cases you'll just
202       need to provide custom implementations of the "_template_modified()"
203       and "_template_content()" methods.  If your provider requires and
204       custom initialisation then you'll also need to implement a new
205       "_init()" method.
206
207       Caching in memory and on disk will still be applied (if enabled) when
208       overriding these methods.
209
210   _template_modified($path)
211       Returns a timestamp of the $path passed in by calling "stat()".  This
212       can be overridden, for example, to return a last modified value from a
213       database.  The value returned should be a timestamp value (as returned
214       by "time()", although a sequence number should work as well.
215
216   _template_content($path)
217       This method returns the content of the template for all "INCLUDE",
218       "PROCESS", and "INSERT" directives.
219
220       When called in scalar context, the method returns the content of the
221       template located at $path, or "undef" if $path is not found.
222
223       When called in list context it returns "($content, $error, $mtime)",
224       where $content is the template content, $error is an error string (e.g.
225       ""$path: File not found""), and $mtime is the template modification
226       time.
227

AUTHOR

229       Andy Wardley <abw@wardley.org> <http://wardley.org/>
230

COPYRIGHT

232       Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
233
234       This module is free software; you can redistribute it and/or modify it
235       under the same terms as Perl itself.
236