Template::Document - phpMan

Che Dong
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 "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
  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();

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