1Template::Document(3) User Contributed Perl DocumentationTemplate::Document(3)
2
6 Template::Document - Compiled template document object
7
9 use Template::Document;
10 $doc = Template::Document->new({
12 BLOCK => sub { # some perl code; return $some_text },
13 DEFBLOCKS => {
14 header => sub { # more perl code; return $some_text },
15 footer => sub { # blah blah blah; return $some_text },
16 },
17 METADATA => {
18 author => 'Andy Wardley',
19 version => 3.14,
20 }
21 }) ⎪⎪ die $Template::Document::ERROR;
22 print $doc->process($context);
24
26 This module defines an object class whose instances represent compiled
27 template documents. The Template::Parser module creates a Tem‐
28 plate::Document instance to encapsulate a template as it is compiled
29 into Perl code.
30 The constructor method, new(), expects a reference to a hash array con‐
32 taining the BLOCK, DEFBLOCKS and METADATA items. The BLOCK item should
33 contain a reference to a Perl subroutine or a textual representation of
34 Perl code, as generated by the Template::Parser module, which is then
35 evaluated into a subroutine reference using eval(). The DEFLOCKS item
36 should reference a hash array containing further named BLOCKs which may
37 be defined in the template. The keys represent BLOCK names and the
38 values should be subroutine references or text strings of Perl code as
39 per the main BLOCK item. The METADATA item should reference a hash
40 array of metadata items relevant to the document.
41 The process() method can then be called on the instantiated Tem‐
43 plate::Document object, passing a reference to a Template::Content
44 object as the first parameter. This will install any locally defined
45 blocks (DEFBLOCKS) in the the contexts() BLOCKS cache (via a call to
46 visit()) so that they may be subsequently resolved by the context. The
47 main BLOCK subroutine is then executed, passing the context reference
48 on as a parameter. The text returned from the template subroutine is
49 then returned by the process() method, after calling the context
50 leave() method to permit cleanup and de-registration of named BLOCKS
51 previously installed.
52 An AUTOLOAD method provides access to the METADATA items for the docu‐
54 ment. The Template::Service module installs a reference to the main
55 Template::Document object in the stash as the 'template' variable.
56 This allows metadata items to be accessed from within templates,
57 including PRE_PROCESS templates.
58 header:
60 <html>
62 <head>
63 <title>[% template.title %]
64 </head>
65 ...
66 Template::Document objects are usually created by the Template::Parser
68 but can be manually instantiated or sub-classed to provide custom tem‐
69 plate components.
70
72 new(\%config)
73 Constructor method which accept a reference to a hash array containing
75 the structure as shown in this example:
76 $doc = Template::Document->new({
78 BLOCK => sub { # some perl code; return $some_text },
79 DEFBLOCKS => {
80 header => sub { # more perl code; return $some_text },
81 footer => sub { # blah blah blah; return $some_text },
82 },
83 METADATA => {
84 author => 'Andy Wardley',
85 version => 3.14,
86 }
87 }) ⎪⎪ die $Template::Document::ERROR;
88 BLOCK and DEFBLOCKS items may be expressed as references to Perl sub‐
90 routines or as text strings containing Perl subroutine definitions, as
91 is generated by the Template::Parser module. These are evaluated into
92 subroutine references using eval().
93 Returns a new Template::Document object or undef on error. The error()
95 class method can be called, or the $ERROR package variable inspected to
96 retrieve the relevant error message.
97 process($context)
99 Main processing routine for the compiled template document. A refer‐
101 ence to a Template::Context object should be passed as the first param‐
102 eter. The method installs any locally defined blocks via a call to the
103 context visit() method, processes it's own template, passing the con‐
104 text reference by parameter and then calls leave() in the context to
105 allow cleanup.
106 print $doc->process($context);
108 Returns a text string representing the generated output for the tem‐
110 plate. Errors are thrown via die().
111 block()
113 Returns a reference to the main BLOCK subroutine.
115 blocks()
117 Returns a reference to the hash array of named DEFBLOCKS subroutines.
119 AUTOLOAD
121 An autoload method returns METADATA items.
123 print $doc->author();
125
127 write_perl_file(\%config)
128 This package subroutine is provided to effect persistence of compiled
130 templates. If the COMPILE_EXT option (to indicate a file extension for
131 saving compiled templates) then the Template::Parser module calls this
132 subroutine before calling the new() constructor. At this stage, the
133 parser has a representation of the template as text strings containing
134 Perl code. We can write that to a file, enclosed in a small wrapper
135 which will allow us to susequently require() the file and have Perl
136 parse and compile it into a Template::Document. Thus we have persis‐
137 tence of compiled templates.
138
140 Andy Wardley <abw@wardley.org>
141 <http://wardley.org/⎪http://wardley.org/>
143
145 2.79, distributed as part of the Template Toolkit version 2.18,
146 released on 09 February 2007.
147
149 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
150 This module is free software; you can redistribute it and/or modify it
152 under the same terms as Perl itself.
153
155 Template, Template::Parser
156perl v5.8.8 2007-02-09 Template::Document(3)