Template::Document - Compiled template document object
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);
This module defines an object class whose instances represent compiled
template documents. The the Template::Parser manpage 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 the Template::Parser manpage 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 the Template::Context manpage
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 the Template::Service manpage 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 the Template::Parser manpage
but can be manually instantiated or sub-classed to provide custom
template components.
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 the Template::Parser manpage 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.
Main processing routine for the compiled template document. A reference to a
the Template::Context manpage 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() .
Returns a reference to the main BLOCK subroutine.
Returns a reference to the hash array of named DEFBLOCKS subroutines.
Returns a reference to a hash of variables used in the template.
This requires the TRACE_VARS
option to be enabled.
An autoload method returns METADATA items.
print $doc->author();
These methods are used internally.
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',
}
});
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 the Template::Parser manpage 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
subsequently require() the file and have Perl parse and compile it into a
Template::Document . Thus we have persistence of compiled templates.
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).
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.
Andy Wardley <abw@wardley.org> http://wardley.org/
Copyright (C) 1996-2013 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.
Template, the Template::Parser manpage
|