Template::Document(3pm)

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   variables()
122       Returns a reference to a hash of variables used in the template.  This
123       requires the TRACE_VARS option to be enabled.
124
125   AUTOLOAD
126       An autoload method returns "METADATA" items.
127
128           print $doc->author();
129

CLASS METHODS

131       These methods are used internally.
132
133   as_perl($content)
134       This method generate a Perl representation of the template.
135
136           my $perl = Template::Document->as_perl({
137               BLOCK     => $main_block,
138               DEFBLOCKS => {
139                   foo   => $foo_block,
140                   bar   => $bar_block,
141               },
142               METADATA  => {
143                   name  => 'my_template',
144               }
145           });
146
147   write_perl_file(\%config)
148       This method is used to write compiled Perl templates to disk.  If the
149       "COMPILE_EXT" option (to indicate a file extension for saving compiled
150       templates) then the Template::Parser module calls this subroutine
151       before calling the new() constructor.  At this stage, the parser has a
152       representation of the template as text strings containing Perl code.
153       We can write that to a file, enclosed in a small wrapper which will
154       allow us to subsequently "require()" the file and have Perl parse and
155       compile it into a "Template::Document".  Thus we have persistence of
156       compiled templates.
157

INTERNAL FUNCTIONS

159   catch_warnings()
160       This is a simple handler used to catch any errors that arise when the
161       compiled Perl template is first evaluated (that is, evaluated by Perl
162       to create a template subroutine at compile, rather than the template
163       being processed at runtime).
164
165   is_utf8()
166       This is mapped to "utf8::is_utf8" for versions of Perl that have it (>
167       5.008) or to "Encode::is_utf8" for Perl 5.008.  Earlier versions of
168       Perl are not supported.
169

AUTHOR

171       Andy Wardley <abw@wardley.org> <http://wardley.org/>
172

COPYRIGHT

174       Copyright (C) 1996-2013 Andy Wardley.  All Rights Reserved.
175
176       This module is free software; you can redistribute it and/or modify it
177       under the same terms as Perl itself.
178