Template::Document

a b c d e f g h i j k l m n o p q r s t u v w x y z _
Template::Document(3)User Contributed Perl DocumentationTemplate::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 "Tem-
       plate::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 Tem-
       plate::Parser module.  This is then evaluated into a subroutine refer-
       ence using "eval()".

       The "DEFLOCKS" item should reference a hash array containing further
       named "BLOCK"s which may be defined in the template. The keys repre-
       sent "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 "Tem-
       plate::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 ref-
       erence on as a parameter. The text returned from the template subrou-
       tine is then returned by the process() method, after calling the con-
       text 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" vari-
       able. 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 sub-classed to pro-
       vide 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 refer-
       ence 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 tem-
       plate.  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" subrou-
       tines.

       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 con-
       taining 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.8.8			  2007-05-29		Template::Document(3)