1Template::Service(3) User Contributed Perl Documentation Template::Service(3)
2
6 Template::Service - General purpose template processing service
7
9 use Template::Service;
10 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 my $output = $service->process($template_name, \%replace)
22 || die $service->error(), "\n";
23
25 The "Template::Service" module implements an object class for providing
26 a consistent template processing service.
27 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 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 use Template;
43 my $template = Template->new({
45 PRE_PROCESS => 'header',
46 POST_PROCESS => 'footer',
47 });
48 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 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 use Template;
58 use Template::Service;
59 my $service = Template::Service->new({
61 PRE_PROCESS => 'header',
62 POST_PROCESS => 'footer',
63 });
64 my $template = Template->new({
66 SERVICE => $service,
67 });
68 The "Template::Service" module can be sub-classed to create custom
70 service handlers.
71 use Template;
73 use MyOrg::Template::Service;
74 my $service = MyOrg::Template::Service->new({
76 PRE_PROCESS => 'header',
77 POST_PROCESS => 'footer',
78 COOL_OPTION => 'enabled in spades',
79 });
80 my $template = Template->new({
82 SERVICE => $service,
83 });
84 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 use Template;
94 $Template::Config::SERVICE = 'MyOrg::Template::Service';
96 my $template = Template->new({
98 PRE_PROCESS => 'header',
99 POST_PROCESS => 'footer',
100 COOL_OPTION => 'enabled in spades',
101 });
102
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 my $service1 = Template::Service->new({
110 PRE_PROCESS => 'header',
111 POST_PROCESS => 'footer',
112 });
113 my $service2 = Template::Service->new( ERROR => 'error.html' );
115 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 my $service = Template::Service->new(\%config)
122 || die Template::Service->error();
123 my $service = Template::Service->new(\%config)
125 || die $Template::Service::ERROR;
126 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 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 $service->process('myfile.html', { title => 'My Test File' })
144 || die $service->error();
145 context()
147 Returns a reference to the internal context object which is, by
148 default, an instance of the Template::Context class.
149
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 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 my $service = Template::Service->new({
164 PRE_PROCESS => 'header',
165 POST_PROCESS => 'footer',
166 };
167 Multiple templates may be specified as a reference to a list. Each is
169 processed in the order defined.
170 my $service = Template::Service->new({
172 PRE_PROCESS => [ 'config', 'header' ],
173 POST_PROCESS => 'footer',
174 };
175 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 my $service = Template::Service->new({
184 PROCESS => 'content',
185 };
186 # processes 'content' instead of 'foo.html'
188 $service->process('foo.html');
189 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 Example "PROCESS" template:
196 <html>
198 <head>
199 <title>[% template.title %]</title>
200 </head>
201 <body>
202 [% PROCESS $template %]
203 </body>
204 </html>
205 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 If specified as a single value then that template will be processed for
214 all uncaught exceptions.
215 my $service = Template::Service->new({
217 ERROR => 'error.html'
218 });
219 If the ERROR/ERRORS item is a hash reference the keys are assumed to be
221 exception types and the relevant template for a given exception will be
222 selected. A "default" template may be provided for the general case.
223 my $service = Template::Service->new({
225 ERRORS => {
226 user => 'user/index.html',
227 dbi => 'error/database',
228 default => 'error/default',
229 },
230 });
231 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 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 use Template::Constants qw( :debug );
245 my $template = Template->new({
247 DEBUG => DEBUG_SERVICE,
248 });
249
251 Andy Wardley <abw@wardley.org> <http://wardley.org/>
252
254 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
255 This module is free software; you can redistribute it and/or modify it
257 under the same terms as Perl itself.
258
260 Template, Template::Context
261
263 Hey! The above document had some coding errors, which are explained
264 below:
265 Around line 517:
267 alternative text 'ERROR/ERRORS' contains non-escaped | or /
268perl v5.16.3 2011-12-20 Template::Service(3)