Template::Service(3pm)

1Template::Service(3)  User Contributed Perl Documentation Template::Service(3)
2
3
4

NAME

6       Template::Service - General purpose template processing service
7

SYNOPSIS

9           use Template::Service;
10
11           my $service = Template::Service->new({
12               PRE_PROCESS  => [ 'config', 'header' ],
13               POST_PROCESS => 'footer',
14               ERROR        => {
15                   user     => 'user/index.html',
16                   dbi      => 'error/database',
17                   default  => 'error/default',
18               },
19           });
20
21           my $output = $service->process($template_name, \%replace)
22               ⎪⎪ die $service->error(), "\n";
23

DESCRIPTION

25       The Template::Service module implements an object class for providing a
26       consistent template processing service.
27
28       Standard header (PRE_PROCESS) and footer (POST_PROCESS) templates may
29       be specified which are prepended and appended to all templates pro‐
30       cessed by the service (but not any other templates or blocks INCLUDEd
31       or PROCESSed from within).  An ERROR hash may be specified which redi‐
32       rects the service to an alternate template file in the case of uncaught
33       exceptions being thrown.  This allows errors to be automatically han‐
34       dled by the service and a guaranteed valid response to be generated
35       regardless of any processing problems encountered.
36
37       A default Template::Service object is created by the Template module.
38       Any Template::Service options may be passed to the Template new() con‐
39       structor method and will be forwarded to the Template::Service con‐
40       structor.
41
42           use Template;
43
44           my $template = Template->new({
45               PRE_PROCESS  => 'header',
46               POST_PROCESS => 'footer',
47           });
48
49       Similarly, the Template::Service constructor will forward all configu‐
50       ration parameters onto other default objects (e.g. Template::Context)
51       that it may need to instantiate.
52
53       A Template::Service object (or subclass/derivative) can be explicitly
54       instantiated and passed to the Template new() constructor method as the
55       SERVICE item.
56
57           use Template;
58           use Template::Service;
59
60           my $service = Template::Service->new({
61               PRE_PROCESS  => 'header',
62               POST_PROCESS => 'footer',
63           });
64
65           my $template = Template->new({
66               SERVICE => $service,
67           });
68
69       The Template::Service module can be sub-classed to create custom ser‐
70       vice handlers.
71
72           use Template;
73           use MyOrg::Template::Service;
74
75           my $service = MyOrg::Template::Service->new({
76               PRE_PROCESS  => 'header',
77               POST_PROCESS => 'footer',
78               COOL_OPTION  => 'enabled in spades',
79           });
80
81           my $template = Template->new({
82               SERVICE => $service,
83           });
84
85       The Template module uses the Template::Config service() factory method
86       to create a default service object when required.  The $Template::Con‐
87       fig::SERVICE package variable may be set to specify an alternate ser‐
88       vice module.  This will be loaded automatically and its new() construc‐
89       tor method called by the service() factory method when a default ser‐
90       vice object is required.  Thus the previous example could be written
91       as:
92
93           use Template;
94
95           $Template::Config::SERVICE = 'MyOrg::Template::Service';
96
97           my $template = Template->new({
98               PRE_PROCESS  => 'header',
99               POST_PROCESS => 'footer',
100               COOL_OPTION  => 'enabled in spades',
101           });
102

METHODS

104       new(\%config)
105
106       The new() constructor method is called to instantiate a Template::Ser‐
107       vice object.  Configuration parameters may be specified as a HASH ref‐
108       erence or as a list of (name => value) pairs.
109
110           my $service1 = Template::Service->new({
111               PRE_PROCESS  => 'header',
112               POST_PROCESS => 'footer',
113           });
114
115           my $service2 = Template::Service->new( ERROR => 'error.html' );
116
117       The new() method returns a Template::Service object (or sub-class) or
118       undef on error.  In the latter case, a relevant error message can be
119       retrieved by the error() class method or directly from the $Tem‐
120       plate::Service::ERROR package variable.
121
122           my $service = Template::Service->new(\%config)
123               ⎪⎪ die Template::Service->error();
124
125           my $service = Template::Service->new(\%config)
126               ⎪⎪ die $Template::Service::ERROR;
127
128       The following configuration items may be specified:
129
130       PRE_PROCESS, POST_PROCESS
131           These values may be set to contain the name(s) of template files
132           (relative to INCLUDE_PATH) which should be processed immediately
133           before and/or after each template.  These do not get added to tem‐
134           plates processed into a document via directives such as INCLUDE,
135           PROCESS, WRAPPER etc.
136
137               my $service = Template::Service->new({
138                   PRE_PROCESS  => 'header',
139                   POST_PROCESS => 'footer',
140               };
141
142           Multiple templates may be specified as a reference to a list.  Each
143           is processed in the order defined.
144
145               my $service = Template::Service->new({
146                   PRE_PROCESS  => [ 'config', 'header' ],
147                   POST_PROCESS => 'footer',
148               };
149
150           Alternately, multiple template may be specified as a single string,
151           delimited by ':'.  This delimiter string can be changed via the
152           DELIMITER option.
153
154               my $service = Template::Service->new({
155                   PRE_PROCESS  => 'config:header',
156                   POST_PROCESS => 'footer',
157               };
158
159           The PRE_PROCESS and POST_PROCESS templates are evaluated in the
160           same variable context as the main document and may define or update
161           variables for subsequent use.
162
163           config:
164
165               [% # set some site-wide variables
166                  bgcolor = '#ffffff'
167                  version = 2.718
168               %]
169
170           header:
171
172               [% DEFAULT title = 'My Funky Web Site' %]
173               <html>
174               <head>
175               <title>[% title %]</title>
176               </head>
177               <body bgcolor="[% bgcolor %]">
178
179           footer:
180
181               <hr>
182               Version [% version %]
183               </body>
184               </html>
185
186           The Template::Document object representing the main template being
187           processed is available within PRE_PROCESS and POST_PROCESS tem‐
188           plates as the 'template' variable.  Metadata items defined via the
189           META directive may be accessed accordingly.
190
191               $service->process('mydoc.html', $vars);
192
193           mydoc.html:
194
195               [% META title = 'My Document Title' %]
196               blah blah blah
197               ...
198
199           header:
200
201               <html>
202               <head>
203               <title>[% template.title %]</title></head>
204               <body bgcolor="[% bgcolor %]">
205
206       PROCESS
207           The PROCESS option may be set to contain the name(s) of template
208           files (relative to INCLUDE_PATH) which should be processed instead
209           of the main template passed to the Template::Service process()
210           method.  This can be used to apply consistent wrappers around all
211           templates, similar to the use of PRE_PROCESS and POST_PROCESS tem‐
212           plates.
213
214               my $service = Template::Service->new({
215                   PROCESS  => 'content',
216               };
217
218               # processes 'content' instead of 'foo.html'
219               $service->process('foo.html');
220
221           A reference to the original template is available in the 'template'
222           variable.  Metadata items can be inspected and the template can be
223           processed by specifying it as a variable reference (i.e. prefixed
224           by '$') to an INCLUDE, PROCESS or WRAPPER directive.
225
226           content:
227
228               <html>
229               <head>
230               <title>[% template.title %]</title>
231               </head>
232
233               <body>
234               [% PROCESS $template %]
235               <hr>
236               &copy; Copyright [% template.copyright %]
237               </body>
238               </html>
239
240           foo.html:
241
242               [% META
243                  title     = 'The Foo Page'
244                  author    = 'Fred Foo'
245                  copyright = '2000 Fred Foo'
246               %]
247               <h1>[% template.title %]</h1>
248               Welcome to the Foo Page, blah blah blah
249
250           output:
251
252               <html>
253               <head>
254               <title>The Foo Page</title>
255               </head>
256
257               <body>
258               <h1>The Foo Page</h1>
259               Welcome to the Foo Page, blah blah blah
260               <hr>
261               &copy; Copyright 2000 Fred Foo
262               </body>
263               </html>
264
265       ERROR
266           The ERROR (or ERRORS if you prefer) configuration item can be used
267           to name a single template or specify a hash array mapping exception
268           types to templates which should be used for error handling.  If an
269           uncaught exception is raised from within a template then the appro‐
270           priate error template will instead be processed.
271
272           If specified as a single value then that template will be processed
273           for all uncaught exceptions.
274
275               my $service = Template::Service->new({
276                   ERROR => 'error.html'
277               });
278
279           If the ERROR item is a hash reference the keys are assumed to be
280           exception types and the relevant template for a given exception
281           will be selected.  A 'default' template may be provided for the
282           general case.  Note that 'ERROR' can be pluralised to 'ERRORS' if
283           you find it more appropriate in this case.
284
285               my $service = Template::Service->new({
286                   ERRORS => {
287                       user     => 'user/index.html',
288                       dbi      => 'error/database',
289                       default  => 'error/default',
290                   },
291               });
292
293           In this example, any 'user' exceptions thrown will cause the
294           'user/index.html' template to be processed, 'dbi' errors are han‐
295           dled by 'error/database' and all others by the 'error/default' tem‐
296           plate.  Any PRE_PROCESS and/or POST_PROCESS templates will also be
297           applied to these error templates.
298
299           Note that exception types are hierarchical and a 'foo' handler will
300           catch all 'foo.*' errors (e.g. foo.bar, foo.bar.baz) if a more spe‐
301           cific handler isn't defined.  Be sure to quote any exception types
302           that contain periods to prevent Perl concatenating them into a sin‐
303           gle string (i.e. "user.passwd" is parsed as 'user'.'passwd').
304
305               my $service = Template::Service->new({
306                   ERROR => {
307                       'user.login'  => 'user/login.html',
308                       'user.passwd' => 'user/badpasswd.html',
309                       'user'        => 'user/index.html',
310                       'default'     => 'error/default',
311                   },
312               });
313
314           In this example, any template processed by the $service object, or
315           other templates or code called from within, can raise a
316           'user.login' exception and have the service redirect to the
317           'user/login.html' template.  Similarly, a 'user.passwd' exception
318           has a specific handling template, 'user/badpasswd.html', while all
319           other 'user' or 'user.*' exceptions cause a redirection to the
320           'user/index.html' page.  All other exception types are handled by
321           'error/default'.
322
323           Exceptions can be raised in a template using the THROW directive,
324
325               [% THROW user.login 'no user id: please login' %]
326
327           or by calling the throw() method on the current Template::Context
328           object,
329
330               $context->throw('user.passwd', 'Incorrect Password');
331               $context->throw('Incorrect Password');    # type 'undef'
332
333           or from Perl code by calling die() with a Template::Exception
334           object,
335
336               die (Template::Exception->new('user.denied', 'Invalid User ID'));
337
338           or by simply calling die() with an error string.  This is automagi‐
339           cally caught and converted to an  exception of 'undef' type which
340           can then be handled in the usual way.
341
342               die "I'm sorry Dave, I can't do that";
343
344       AUTO_RESET
345           The AUTO_RESET option is set by default and causes the local BLOCKS
346           cache for the Template::Context object to be reset on each call to
347           the Template process() method.  This ensures that any BLOCKs
348           defined within a template will only persist until that template is
349           finished processing.  This prevents BLOCKs defined in one process‐
350           ing request from interfering with other independent requests subse‐
351           quently processed by the same context object.
352
353           The BLOCKS item may be used to specify a default set of block defi‐
354           nitions for the Template::Context object.  Subsequent BLOCK defini‐
355           tions in templates will over-ride these but they will be reinstated
356           on each reset if AUTO_RESET is enabled (default), or if the Tem‐
357           plate::Context reset() method is called.
358
359       DEBUG
360           The DEBUG option can be used to enable debugging messages from the
361           Template::Service module by setting it to include the DEBUG_SERVICE
362           value.
363
364               use Template::Constants qw( :debug );
365
366               my $template = Template->new({
367                   DEBUG => DEBUG_SERVICE,
368               });
369
370       process($input, \%replace)
371
372       The process() method is called to process a template specified as the
373       first parameter, $input.  This may be a file name, file handle (e.g.
374       GLOB or IO::Handle) or a reference to a text string containing the tem‐
375       plate text.  An additional hash reference may be passed containing tem‐
376       plate variable definitions.
377
378       The method processes the template, adding any PRE_PROCESS or
379       POST_PROCESS templates defined, and returns the output text.  An
380       uncaught exception thrown by the template will be handled by a relevant
381       ERROR handler if defined.  Errors that occur in the PRE_PROCESS or
382       POST_PROCESS templates, or those that occur in the main input template
383       and aren't handled, cause the method to return undef to indicate fail‐
384       ure.  The appropriate error message can be retrieved via the error()
385       method.
386
387           $service->process('myfile.html', { title => 'My Test File' })
388               ⎪⎪ die $service->error();
389
390       context()
391
392       Returns a reference to the internal context object which is, by
393       default, an instance of the Template::Context class.
394
395       error()
396
397       Returns the most recent error message.
398

AUTHOR

400       Andy Wardley <abw@wardley.org>
401
402       <http://wardley.org/⎪http://wardley.org/>
403

VERSION

405       2.91, distributed as part of the Template Toolkit version 2.18,
406       released on 09 February 2007.
407

COPYRIGHT

409         Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
410
411       This module is free software; you can redistribute it and/or modify it
412       under the same terms as Perl itself.
413