[%# # IMPORTANT NOTE # This documentation is generated automatically from source # templates. Any changes you make here may be lost. # # The 'docsrc' documentation source bundle is available for download # from http://www.template-toolkit.org/docs.html and contains all # the source templates, XML files, scripts, etc., from which the # documentation for the Template Toolkit is built. -%] [% META book = 'Modules' page = 'Document' %] [% WRAPPER toc; PROCESS tocitem title ="SYNOPSIS" subs = []; PROCESS tocitem title ="DESCRIPTION" subs = []; PROCESS tocitem title ="METHODS" subs = [ "new(\\%config)", "process(\$context)", "block()", "blocks()", "AUTOLOAD" ]; PROCESS tocitem title ="PACKAGE SUB-ROUTINES" subs = [ "write_perl_file(\\%config)" ]; PROCESS tocitem title ="AUTHOR" subs = []; PROCESS tocitem title ="VERSION" subs = []; PROCESS tocitem title ="COPYRIGHT" subs = []; PROCESS tocitem title ="SEE ALSO" subs = []; END %] [% WRAPPER section title="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);

[%- END %] [% WRAPPER section title="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 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 instantiated 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 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>[% tt_start_tag %] template.title [% tt_end_tag %]
    </head>
    ...

Template::Document objects are usually created by the Template::Parser but can be manually instantiated or sub-classed to provide custom template components.

[%- END %] [% WRAPPER section title="METHODS" -%][% WRAPPER subsection title = "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.

[%- END %] [% WRAPPER subsection title = "process(\$context)" -%]

Main 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 it's own template, passing the context reference by 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().

[%- END %] [% WRAPPER subsection title = "block()" -%]

Returns a reference to the main BLOCK subroutine.

[%- END %] [% WRAPPER subsection title = "blocks()" -%]

Returns a reference to the hash array of named DEFBLOCKS subroutines.

[%- END %] [% WRAPPER subsection title = "AUTOLOAD" -%]

An autoload method returns METADATA items.

    print $doc->author();

[%- END %] [%- END %] [% WRAPPER section title="PACKAGE SUB-ROUTINES" -%][% WRAPPER subsection title = "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 persistance of compiled templates.

[%- END %] [%- END %] [% WRAPPER section title="AUTHOR" -%]

Andy Wardley <abw@andywardley.com>

[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]

[%- END %] [% WRAPPER section title="VERSION" -%]

2.55, distributed as part of the Template Toolkit version 2.08, released on 30 July 2002.

[%- END %] [% WRAPPER section title="COPYRIGHT" -%]

  Copyright (C) 1996-2002 Andy Wardley.  All Rights Reserved.
  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.

[%- END %] [% WRAPPER section title="SEE ALSO" -%]

[% ttlink('Template', 'Template') -%], [% ttlink('Template::Parser', 'Template::Parser') -%]

[%- END %]