---
name: "Template::Document"
section: "3pm"
platform: "linux"
package: "perl-template-toolkit"
version: "3.106-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Template::Document"
---

# Template::Document(3pm)

Compiled template document object

## 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 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 `"DEFBLOCKS"` 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

### 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 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()

Returns a reference to the main `"BLOCK"` subroutine.

### blocks()

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

### variables()

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

### meta()

Return a reference to a hash of any META items defined in the template.

### AUTOLOAD

An autoload method returns `"METADATA"` items.

```
    print $doc->author();
```

## CLASS METHODS

These methods are used internally.

### as\_perl($content)

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)

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 subsequently `require()` the file and have Perl parse and compile it into a `"Template::Document"`.  Thus we have persistence of compiled templates.

## INTERNAL FUNCTIONS

### catch\_warnings()

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

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

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

## COPYRIGHT

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