Template::Document(3) User Contributed Perl DocumentationTemplate::Document(3)NAMETemplate::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.
AUTOLOAD
An autoload method returns "METADATA" items.
print $doc->author();
PACKAGE SUB-ROUTINES
write_perl_file(\%config)
This package subroutine is provided to effect persistence of compiled
templates. 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.
AUTHOR
Andy Wardley <abw@wardley.org> <http://wardley.org/>
COPYRIGHT
Copyright (C) 1996-2007 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
perl v5.10.1 2010-04-30 Template::Document(3)
