template::document(3)
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 repre
sent compiled template documents. The Template::Parser
module creates a Template::Document instance to encapsu
late 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, which is then
evaluated into a subroutine reference using eval(). The
DEFLOCKS item should reference a hash array containing
further named BLOCKs 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 instanti
ated Template::Document object, passing a reference to a
Template::Content object as the first parameter. This
will install any locally defined blocks (DEFBLOCKS) in the
the contexts() BLOCKS cache (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 pro_
cess() method, after calling the context leave() method to
permit cleanup and de-registration of named BLOCKS previ
ously 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 Tem
plate::Parser but can be manually instantiated or subclassed 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 Tem
plate::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 docu
ment. 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 it's own template, passing the context
reference by parameter and then calls leave() in the con text 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 persistance
of compiled templates. If the COMPILE_EXT option (to
indicate a file extension for saving compiled templates)
then the Template::Parser module call 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 per
sistance of compiled templates.
AUTHOR
Andy Wardley <abw@andywardley.com>
<http://www.andywardley.com/|http://www.andywardley.com/>
VERSION
2.55, distributed as part of the Template Toolkit version
2.08, released on 30 July 2002.
COPYRIGHT
- Copyright (C) 1996-2002 Andy Wardley. All Rights Re
- served.
Copyright (C) 1998-2002 Canon Research Centre Europe - Ltd.
- 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