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   load($name)
48       Loads a template without parsing or compiling it.  This is used by the
49       the INSERT directive.
50
51   store($name, $template)
52       Stores the compiled template, $template, in the cache under the name,
53       $name.  Susbequent calls to fetch($name) will return this template in
54       preference to any disk-based file.
55
56   include_path(\@newpath)
57       Accessor method for the "INCLUDE_PATH" setting.  If called with an
58       argument, this method will replace the existing "INCLUDE_PATH" with the
59       new value.
60
61   paths()
62       This method generates a copy of the "INCLUDE_PATH" list.  Any elements
63       in the list which are dynamic generators (e.g. references to
64       subroutines or objects implementing a paths() method) will be called
65       and the list of directories returned merged into the output list.
66
67       It is possible to provide a generator which returns itself, thus
68       sending this method into an infinite loop.  To detect and prevent this
69       from happening, the $MAX_DIRS package variable, set to 64 by default,
70       limits the maximum number of paths that can be added to, or generated
71       for the output list.  If this number is exceeded then the method will
72       immediately return an error reporting as much.
73

CONFIGURATION OPTIONS

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

SUBCLASSING

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

AUTHOR

232       Andy Wardley <abw@wardley.org> <http://wardley.org/>
233

COPYRIGHT

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