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 "DEFBLOCKS" 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   meta()
126       Return a reference to a hash of any META items defined in the template.
127
128   AUTOLOAD
129       An autoload method returns "METADATA" items.
130
131           print $doc->author();
132

CLASS METHODS

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

INTERNAL FUNCTIONS

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

AUTHOR

174       Andy Wardley <abw@wardley.org> <http://wardley.org/>
175

COPYRIGHT

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