NAME¶
Template::Document - Compiled template document object
SYNOPSIS¶
use Template::Document;
$doc = Template::Document->new({
BLOCK => sub { # some perl code; return $some_text },
DEFBLOCKS => {
header => sub { # more perl code; return $some_text },
footer => sub { # blah blah blah; return $some_text },
},
METADATA => {
author => 'Andy Wardley',
version => 3.14,
}
}) || die $Template::Document::ERROR;
print $doc->process($context);
DESCRIPTION¶
This module defines an object class whose instances represent compiled template
documents. The Template::Parser module creates a
"Template::Document" instance to encapsulate a template as it is
compiled into Perl code.
The constructor method,
new(), expects a reference to a hash array
containing the "BLOCK", "DEFBLOCKS" and
"METADATA" items.
The "BLOCK" item should contain a reference to a Perl subroutine or a
textual representation of Perl code, as generated by the Template::Parser
module. This is then evaluated into a subroutine reference using
"eval()".
The "DEFLOCKS" item should reference a hash array containing further
named "BLOCK"s which may be defined in the template. The keys
represent "BLOCK" names and the values should be subroutine
references or text strings of Perl code as per the main "BLOCK"
item.
The "METADATA" item should reference a hash array of metadata items
relevant to the document.
The
process() method can then be called on the instantiated
"Template::Document" object, passing a reference to a
Template::Context object as the first parameter. This will install any locally
defined blocks ("DEFBLOCKS") in the "BLOCKS" cache in the
context (via a call to
visit()) so that they may be subsequently
resolved by the context. The main "BLOCK" subroutine is then
executed, passing the context reference on as a parameter. The text returned
from the template subroutine is then returned by the
process() method,
after calling the context
leave() method to permit cleanup and
de-registration of named "BLOCKS" previously installed.
An "AUTOLOAD" method provides access to the "METADATA" items
for the document. The Template::Service module installs a reference to the
main "Template::Document" object in the stash as the
"template" variable. This allows metadata items to be accessed from
within templates, including "PRE_PROCESS" templates.
header:
<html>
<head>
<title>[% template.title %]
</head>
...
"Template::Document" objects are usually created by the
Template::Parser but can be manually instantiated or sub-classed to provide
custom template components.
METHODS¶
new(\%config)¶
Constructor method which accept a reference to a hash array containing the
structure as shown in this example:
$doc = Template::Document->new({
BLOCK => sub { # some perl code; return $some_text },
DEFBLOCKS => {
header => sub { # more perl code; return $some_text },
footer => sub { # blah blah blah; return $some_text },
},
METADATA => {
author => 'Andy Wardley',
version => 3.14,
}
}) || die $Template::Document::ERROR;
"BLOCK" and "DEFBLOCKS" items may be expressed as references
to Perl subroutines or as text strings containing Perl subroutine definitions,
as is generated by the Template::Parser module. These are evaluated into
subroutine references using "eval()".
Returns a new "Template::Document" object or "undef" on
error. The
error() class method can be called, or the $ERROR package
variable inspected to retrieve the relevant error message.
process($context)¶
Main processing routine for the compiled template document. A reference to a
Template::Context object should be passed as the first parameter. The method
installs any locally defined blocks via a call to the context
visit()
method, processes its own template, (passing the context reference as a
parameter) and then calls
leave() in the context to allow cleanup.
print $doc->process($context);
Returns a text string representing the generated output for the template. Errors
are thrown via "die()".
block()¶
Returns a reference to the main "BLOCK" subroutine.
blocks()¶
Returns a reference to the hash array of named "DEFBLOCKS"
subroutines.
variables()¶
Returns a reference to a hash of variables used in the template. This requires
the TRACE_VARS option to be enabled.
AUTOLOAD¶
An autoload method returns "METADATA" items.
print $doc->author();
CLASS METHODS¶
These methods are used internally.
as_perl($content)¶
This method generate a Perl representation of the template.
my $perl = Template::Document->as_perl({
BLOCK => $main_block,
DEFBLOCKS => {
foo => $foo_block,
bar => $bar_block,
},
METADATA => {
name => 'my_template',
}
});
write_perl_file(\%config)¶
This method is used to write compiled Perl templates to disk. If the
"COMPILE_EXT" option (to indicate a file extension for saving
compiled templates) then the Template::Parser module calls this subroutine
before calling the
new() constructor. At this stage, the parser has a
representation of the template as text strings containing Perl code. We can
write that to a file, enclosed in a small wrapper which will allow us to
susequently "require()" the file and have Perl parse and compile it
into a "Template::Document". Thus we have persistence of compiled
templates.
INTERNAL FUNCTIONS¶
catch_warnings()¶
This is a simple handler used to catch any errors that arise when the compiled
Perl template is first evaluated (that is, evaluated by Perl to create a
template subroutine at compile, rather than the template being processed at
runtime).
is_utf8()¶
This is mapped to "utf8::is_utf8" for versions of Perl that have it
(> 5.008) or to "Encode::is_utf8" for Perl 5.008. Earlier
versions of Perl are not supported.
AUTHOR¶
Andy Wardley <abw@wardley.org> <
http://wardley.org/>
COPYRIGHT¶
Copyright (C) 1996-2012 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.
SEE ALSO¶
Template, Template::Parser