Template::Document
Author: Andy Wardley

TT2 Home Page

- Modules
- Template::*
- Document.pm

Click to view the menu. It's very nice. Click to hide the menu and go all widescreen!
Back

#### Template::Directive

Perl code generator for template directives Up

#### Template::* Modules

Next

#### Template::Exception

Exception handling class module

# Template::Document

## Compiled template document object

# Contents

Top

# SYNOPSIS

Top

    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

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 `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 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

Top

## new(\%config)

Top

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)

Top

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 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.

## variables()

Top

Returns a reference to a hash of variables used in the template. This requires the TRACE_VARS option to be enabled.

## AUTOLOAD

Top

An autoload method returns `METADATA` items.

    print $doc->author();

# CLASS METHODS

Top

These methods are used internally.

## as_perl($content)

Top

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',
        }
    });

## write_perl_file(\%config)

Top

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 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.

# INTERNAL FUNCTIONS

Top

## catch_warnings()

Top

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).

## is_utf8()

Top

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.

# AUTHOR

Top

Andy Wardley <abw@wardley.org> http://wardley.org/

# COPYRIGHT

Top

Copyright (C) 1996-2012 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

Top

Template, Template::Parser

http://template-toolkit.org/docs/modules/Template/Document.html