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
26       a 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
30       processed by the service (but not any other templates or blocks
31       "INCLUDE"d or "PROCESS"ed from within). An ERROR hash may be specified
32       which redirects the service to an alternate template file in the case
33       of uncaught exceptions being thrown. This allows errors to be
34       automatically handled by the service and a guaranteed valid response to
35       be generated 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()
39       constructor method and will be forwarded to the Template::Service
40       constructor.
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
50       configuration parameters onto other default objects (e.g.
51       Template::Context) that it may need to instantiate.
52
53       A "Template::Service" object (or subclass) 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
70       service 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
87       $Template::Config::SERVICE package variable may be set to specify an
88       alternate service module. This will be loaded automatically and its
89       new() constructor method called by the service() factory method when a
90       default service object is required. Thus the previous example could be
91       written 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       The "new()" constructor method is called to instantiate a
106       "Template::Service" object.  Configuration parameters may be specified
107       as a HASH reference or as a list of "name => value" pairs.
108
109           my $service1 = Template::Service->new({
110               PRE_PROCESS  => 'header',
111               POST_PROCESS => 'footer',
112           });
113
114           my $service2 = Template::Service->new( ERROR => 'error.html' );
115
116       The "new()" method returns a "Template::Service" object or "undef" on
117       error. In the latter case, a relevant error message can be retrieved by
118       the error() class method or directly from the $Template::Service::ERROR
119       package variable.
120
121           my $service = Template::Service->new(\%config)
122               || die Template::Service->error();
123
124           my $service = Template::Service->new(\%config)
125               || die $Template::Service::ERROR;
126
127   process($input, \%replace)
128       The "process()" method is called to process a template specified as the
129       first parameter, $input. This may be a file name, file handle (e.g.
130       "GLOB" or "IO::Handle") or a reference to a text string containing the
131       template text. An additional hash reference may be passed containing
132       template variable definitions.
133
134       The method processes the template, adding any PRE_PROCESS or
135       POST_PROCESS templates defined, and returns the output text. An
136       uncaught exception thrown by the template will be handled by a relevant
137       ERROR handler if defined. Errors that occur in the PRE_PROCESS or
138       POST_PROCESS templates, or those that occur in the main input template
139       and aren't handled, cause the method to return "undef" to indicate
140       failure. The appropriate error message can be retrieved via the error()
141       method.
142
143           $service->process('myfile.html', { title => 'My Test File' })
144               || die $service->error();
145
146   context()
147       Returns a reference to the internal context object which is, by
148       default, an instance of the Template::Context class.
149

CONFIGURATION OPTIONS

151       The following list summarises the configuration options that can be
152       provided to the "Template::Service" new() constructor. Please consult
153       Template::Manual::Config for further details and examples of each
154       configuration option in use.
155
156   PRE_PROCESS, POST_PROCESS
157       The PRE_PROCESS and POST_PROCESS options may be set to contain the
158       name(s) of template files which should be processed immediately before
159       and/or after each template. These do not get added to templates
160       processed into a document via directives such as "INCLUDE" "PROCESS",
161       "WRAPPER", etc.
162
163           my $service = Template::Service->new({
164               PRE_PROCESS  => 'header',
165               POST_PROCESS => 'footer',
166           };
167
168       Multiple templates may be specified as a reference to a list.  Each is
169       processed in the order defined.
170
171           my $service = Template::Service->new({
172               PRE_PROCESS  => [ 'config', 'header' ],
173               POST_PROCESS => 'footer',
174           };
175
176   PROCESS
177       The PROCESS option may be set to contain the name(s) of template files
178       which should be processed instead of the main template passed to the
179       "Template::Service" process() method. This can be used to apply
180       consistent wrappers around all templates, similar to the use of
181       PRE_PROCESS and POST_PROCESS templates.
182
183           my $service = Template::Service->new({
184               PROCESS  => 'content',
185           };
186
187           # processes 'content' instead of 'foo.html'
188           $service->process('foo.html');
189
190       A reference to the original template is available in the "template"
191       variable.  Metadata items can be inspected and the template can be
192       processed by specifying it as a variable reference (i.e. prefixed by
193       '"$"') to an "INCLUDE", "PROCESS" or "WRAPPER" directive.
194
195       Example "PROCESS" template:
196
197           <html>
198             <head>
199               <title>[% template.title %]</title>
200             </head>
201             <body>
202             [% PROCESS $template %]
203             </body>
204           </html>
205
206   ERROR
207       The ERROR (or "ERRORS" if you prefer) configuration item can be used to
208       name a single template or specify a hash array mapping exception types
209       to templates which should be used for error handling. If an uncaught
210       exception is raised from within a template then the appropriate error
211       template will instead be processed.
212
213       If specified as a single value then that template will be processed for
214       all uncaught exceptions.
215
216           my $service = Template::Service->new({
217               ERROR => 'error.html'
218           });
219
220       If the ERROR or ERRORS item is a hash reference the keys are assumed to
221       be exception types and the relevant template for a given exception will
222       be selected. A "default" template may be provided for the general case.
223
224           my $service = Template::Service->new({
225               ERRORS => {
226                   user     => 'user/index.html',
227                   dbi      => 'error/database',
228                   default  => 'error/default',
229               },
230           });
231
232   AUTO_RESET
233       The AUTO_RESET option is set by default and causes the local "BLOCKS"
234       cache for the Template::Context object to be reset on each call to the
235       Template process() method.  This ensures that any "BLOCK"s defined
236       within a template will only persist until that template is finished
237       processing.
238
239   DEBUG
240       The DEBUG option can be used to enable debugging messages from the
241       "Template::Service" module by setting it to include the "DEBUG_SERVICE"
242       value.
243
244           use Template::Constants qw( :debug );
245
246           my $template = Template->new({
247               DEBUG => DEBUG_SERVICE,
248           });
249

AUTHOR

251       Andy Wardley <abw@wardley.org> <http://wardley.org/>
252

COPYRIGHT

254       Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
255
256       This module is free software; you can redistribute it and/or modify it
257       under the same terms as Perl itself.
258