Contents
TopSYNOPSIS
Topuse 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
Top
                      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 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 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
Topnew(\%config)
TopConstructor 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)
TopMain 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()
Top
                          Returns a reference to the main BLOCK subroutine.
                        
blocks()
Top
                          Returns a reference to the hash array of named DEFBLOCKS
                          subroutines.
                        
AUTOLOAD
Top
                          An autoload method returns METADATA items.
                        
print $doc->author();
PACKAGE SUB-ROUTINES
Topwrite_perl_file(\%config)
Top
                          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
TopAndy Wardley <abw@wardley.org> http://wardley.org/
COPYRIGHT
TopCopyright (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.