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.

AUTOLOAD¶

An autoload method returns "METADATA" items.

    print $doc->author();

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

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.