1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "Template::Document 3"
132 .TH Template::Document 3 "2009-06-17" "perl v5.8.7" "User Contributed Perl Documentation"
134 Template::Document \- Compiled template document object
136 .IX Header "SYNOPSIS"
138 \& use Template::Document;
142 \& $doc = Template::Document\->new({
143 \& BLOCK => sub { # some perl code; return $some_text },
145 \& header => sub { # more perl code; return $some_text },
146 \& footer => sub { # blah blah blah; return $some_text },
149 \& author => 'Andy Wardley',
152 \& }) || die $Template::Document::ERROR;
156 \& print $doc\->process($context);
159 .IX Header "DESCRIPTION"
160 This module defines an object class whose instances represent compiled
161 template documents. The Template::Parser module creates a
162 \&\f(CW\*(C`Template::Document\*(C'\fR instance to encapsulate a template as it is compiled
165 The constructor method, \fInew()\fR, expects a reference to a hash array
166 containing the \f(CW\*(C`BLOCK\*(C'\fR, \f(CW\*(C`DEFBLOCKS\*(C'\fR and \f(CW\*(C`METADATA\*(C'\fR items.
168 The \f(CW\*(C`BLOCK\*(C'\fR item should contain a reference to a Perl subroutine or a textual
169 representation of Perl code, as generated by the Template::Parser module.
170 This is then evaluated into a subroutine reference using \f(CW\*(C`eval()\*(C'\fR.
172 The \f(CW\*(C`DEFLOCKS\*(C'\fR item should reference a hash array containing further named
173 \&\f(CW\*(C`BLOCK\*(C'\fRs which may be defined in the template. The keys represent \f(CW\*(C`BLOCK\*(C'\fR
174 names and the values should be subroutine references or text strings of Perl
175 code as per the main \f(CW\*(C`BLOCK\*(C'\fR item.
177 The \f(CW\*(C`METADATA\*(C'\fR item should reference a hash array of metadata items relevant
180 The \fIprocess()\fR method can then be called on the instantiated
181 \&\f(CW\*(C`Template::Document\*(C'\fR object, passing a reference to a Template::Context
182 object as the first parameter. This will install any locally defined blocks
183 (\f(CW\*(C`DEFBLOCKS\*(C'\fR) in the \f(CW\*(C`BLOCKS\*(C'\fR cache in the context (via a call to
184 \&\fIvisit()\fR) so that they may be subsequently
185 resolved by the context. The main \f(CW\*(C`BLOCK\*(C'\fR subroutine is then executed,
186 passing the context reference on as a parameter. The text returned from the
187 template subroutine is then returned by the \fIprocess()\fR method, after calling
188 the context \fIleave()\fR method to permit cleanup and
189 de-registration of named \f(CW\*(C`BLOCKS\*(C'\fR previously installed.
191 An \f(CW\*(C`AUTOLOAD\*(C'\fR method provides access to the \f(CW\*(C`METADATA\*(C'\fR items for the
192 document. The Template::Service module installs a reference to the main
193 \&\f(CW\*(C`Template::Document\*(C'\fR object in the stash as the \f(CW\*(C`template\*(C'\fR variable. This allows
194 metadata items to be accessed from within templates, including \f(CW\*(C`PRE_PROCESS\*(C'\fR
202 \& <title>[% template.title %]
207 \&\f(CW\*(C`Template::Document\*(C'\fR objects are usually created by the Template::Parser
208 but can be manually instantiated or sub-classed to provide custom
213 .IX Subsection "new(%config)"
214 Constructor method which accept a reference to a hash array containing the
215 structure as shown in this example:
218 \& $doc = Template::Document\->new({
219 \& BLOCK => sub { # some perl code; return $some_text },
221 \& header => sub { # more perl code; return $some_text },
222 \& footer => sub { # blah blah blah; return $some_text },
225 \& author => 'Andy Wardley',
228 \& }) || die $Template::Document::ERROR;
231 \&\f(CW\*(C`BLOCK\*(C'\fR and \f(CW\*(C`DEFBLOCKS\*(C'\fR items may be expressed as references to Perl subroutines
232 or as text strings containing Perl subroutine definitions, as is generated
233 by the Template::Parser module. These are evaluated into subroutine references
234 using \f(CW\*(C`eval()\*(C'\fR.
236 Returns a new \f(CW\*(C`Template::Document\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR on error. The
237 \&\fIerror()\fR class method can be called, or the \f(CW$ERROR\fR
238 package variable inspected to retrieve the relevant error message.
239 .Sh "process($context)"
240 .IX Subsection "process($context)"
241 Main processing routine for the compiled template document. A reference to a
242 Template::Context object should be passed as the first parameter. The
243 method installs any locally defined blocks via a call to the context
244 \&\fIvisit()\fR method, processes its own template,
245 (passing the context reference as a parameter) and then calls
246 \&\fIleave()\fR in the context to allow cleanup.
249 \& print $doc\->process($context);
252 Returns a text string representing the generated output for the template.
253 Errors are thrown via \f(CW\*(C`die()\*(C'\fR.
255 .IX Subsection "block()"
256 Returns a reference to the main \f(CW\*(C`BLOCK\*(C'\fR subroutine.
258 .IX Subsection "blocks()"
259 Returns a reference to the hash array of named \f(CW\*(C`DEFBLOCKS\*(C'\fR subroutines.
260 .Sh "\s-1AUTOLOAD\s0"
261 .IX Subsection "AUTOLOAD"
262 An autoload method returns \f(CW\*(C`METADATA\*(C'\fR items.
265 \& print $doc\->author();
267 .SH "PACKAGE SUB-ROUTINES"
268 .IX Header "PACKAGE SUB-ROUTINES"
269 .Sh "write_perl_file(\e%config)"
270 .IX Subsection "write_perl_file(%config)"
271 This package subroutine is provided to effect persistence of compiled
272 templates. If the \f(CW\*(C`COMPILE_EXT\*(C'\fR option (to indicate a file extension
273 for saving compiled templates) then the Template::Parser module calls
274 this subroutine before calling the \fInew()\fR constructor. At this stage,
275 the parser has a representation of the template as text strings
276 containing Perl code. We can write that to a file, enclosed in a
277 small wrapper which will allow us to susequently \f(CW\*(C`require()\*(C'\fR the file
278 and have Perl parse and compile it into a \f(CW\*(C`Template::Document\*(C'\fR. Thus we
279 have persistence of compiled templates.
282 Andy Wardley <abw@wardley.org> <http://wardley.org/>
284 .IX Header "COPYRIGHT"
285 Copyright (C) 1996\-2007 Andy Wardley. All Rights Reserved.
287 This module is free software; you can redistribute it and/or
288 modify it under the same terms as Perl itself.
290 .IX Header "SEE ALSO"
291 Template, Template::Parser