1Template::Document(3) User Contributed Perl DocumentationTemplate::Document(3)
2
3
4

NAME

6       Template::Document - Compiled template document object
7

SYNOPSIS

9           use Template::Document;
10
11           $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
23           print $doc->process($context);
24

DESCRIPTION

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
31       The constructor method, new(), expects a reference to a hash array
32       containing the "BLOCK", "DEFBLOCKS" and "METADATA" items.
33
34       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
39       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
44       The "METADATA" item should reference a hash array of metadata items
45       relevant to the document.
46
47       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
58       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
64       header:
65
66           <html>
67           <head>
68           <title>[% template.title %]
69           </head>
70           ...
71
72       "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

METHODS

77   new(\%config)
78       Constructor method which accept a reference to a hash array containing
79       the structure as shown in this example:
80
81           $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
93       "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
98       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
102   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
110           print $doc->process($context);
111
112       Returns a text string representing the generated output for the
113       template.  Errors are thrown via "die()".
114
115   block()
116       Returns a reference to the main "BLOCK" subroutine.
117
118   blocks()
119       Returns a reference to the hash array of named "DEFBLOCKS" subroutines.
120
121   AUTOLOAD
122       An autoload method returns "METADATA" items.
123
124           print $doc->author();
125

PACKAGE SUB-ROUTINES

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

AUTHOR

139       Andy Wardley <abw@wardley.org> <http://wardley.org/>
140
142       Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
143
144       This module is free software; you can redistribute it and/or modify it
145       under the same terms as Perl itself.
146

SEE ALSO

148       Template, Template::Parser
149
150
151
152perl v5.12.0                      2009-06-17             Template::Document(3)
Impressum