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
28 "Template::Document" instance to encapsulate a template as it is
29 compiled into Perl code.
30 The constructor method, new(), expects a reference to a hash array
32 containing the "BLOCK", "DEFBLOCKS" and "METADATA" items.
33 The "BLOCK" item should contain a reference to a Perl subroutine or a
35 textual representation of Perl code, as generated by the
36 Template::Parser module. This is then evaluated into a subroutine
37 reference using "eval()".
38 The "DEFLOCKS" item should reference a hash array containing further
40 named "BLOCK"s which may be defined in the template. The keys represent
41 "BLOCK" names and the values should be subroutine references or text
42 strings of Perl code as per the main "BLOCK" item.
43 The "METADATA" item should reference a hash array of metadata items
45 relevant to the document.
46 The process() method can then be called on the instantiated
48 "Template::Document" object, passing a reference to a Template::Context
49 object as the first parameter. This will install any locally defined
50 blocks ("DEFBLOCKS") in the "BLOCKS" cache in the context (via a call
51 to visit()) so that they may be subsequently resolved by the context.
52 The main "BLOCK" subroutine is then executed, passing the context
53 reference on as a parameter. The text returned from the template
54 subroutine is then returned by the process() method, after calling the
55 context leave() method to permit cleanup and de-registration of named
56 "BLOCKS" previously installed.
57 An "AUTOLOAD" method provides access to the "METADATA" items for the
59 document. The Template::Service module installs a reference to the main
60 "Template::Document" object in the stash as the "template" variable.
61 This allows metadata items to be accessed from within templates,
62 including "PRE_PROCESS" templates.
63 header:
65 <html>
67 <head>
68 <title>[% template.title %]
69 </head>
70 ...
71 "Template::Document" objects are usually created by the
73 Template::Parser but can be manually instantiated or sub-classed to
74 provide custom template components.
75
77 new(\%config)
78 Constructor method which accept a reference to a hash array containing
79 the structure as shown in this example:
80 $doc = Template::Document->new({
82 BLOCK => sub { # some perl code; return $some_text },
83 DEFBLOCKS => {
84 header => sub { # more perl code; return $some_text },
85 footer => sub { # blah blah blah; return $some_text },
86 },
87 METADATA => {
88 author => 'Andy Wardley',
89 version => 3.14,
90 }
91 }) || die $Template::Document::ERROR;
92 "BLOCK" and "DEFBLOCKS" items may be expressed as references to Perl
94 subroutines or as text strings containing Perl subroutine definitions,
95 as is generated by the Template::Parser module. These are evaluated
96 into subroutine references using "eval()".
97 Returns a new "Template::Document" object or "undef" on error. The
99 error() class method can be called, or the $ERROR package variable
100 inspected to retrieve the relevant error message.
101 process($context)
103 Main processing routine for the compiled template document. A reference
104 to a Template::Context object should be passed as the first parameter.
105 The method installs any locally defined blocks via a call to the
106 context visit() method, processes its own template, (passing the
107 context reference as a parameter) and then calls leave() in the context
108 to allow cleanup.
109 print $doc->process($context);
111 Returns a text string representing the generated output for the
113 template. Errors are thrown via "die()".
114 block()
116 Returns a reference to the main "BLOCK" subroutine.
117 blocks()
119 Returns a reference to the hash array of named "DEFBLOCKS" subroutines.
120 AUTOLOAD
122 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
129 templates. If the "COMPILE_EXT" option (to indicate a file extension
130 for saving compiled templates) then the Template::Parser module calls
131 this subroutine before calling the new() constructor. At this stage,
132 the parser has a representation of the template as text strings
133 containing Perl code. We can write that to a file, enclosed in a small
134 wrapper which will allow us to susequently "require()" the file and
135 have Perl parse and compile it into a "Template::Document". Thus we
136 have persistence of compiled templates.
137
139 Andy Wardley <abw@wardley.org> <http://wardley.org/>
140
142 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
143 This module is free software; you can redistribute it and/or modify it
145 under the same terms as Perl itself.
146
148 Template, Template::Parser
149perl v5.10.1 2009-06-17 Template::Document(3)