Template::Document(3)          User Contributed Perl Documentation          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 represent compiled template documents.
       The Template::Parser module creates a "Template::Document" instance to encapsulate a tem-
       plate 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 representa-
       tion 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 docu-
       ment.

       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 Tem-
       plate::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: