NAME

Template::Context - object class representing a runtime context in which templates are rendered.

SYNOPSIS

    use Template::Context;

    $context = Template::Context->new(\%cfg);

    $error   = $context->process($template);

    # cleanup
    $context->old();

    $context->localise(\%vars);
    $context->delocalise();

    $context->output($text);
    $context->error($text);
    $context->redirect($what, $where);

    $context->throw($type, $info);
    $context->catch($type, $handler);

    ($plugin, $error) = $context->use_plugin($name, \@params);
    ($filter, $error) = $context->use_filter($name, \@params, $alias);

DESCRIPTION

The Template::Context module defines an object which represents a runtime context in which a template is rendered. The context reference is passed down through the processing engine, allowing template directives and user code to generate output, retrieve and update variable values, render other template documents, and so on.

The context defines the variables that exist for the template to access and what values they have (a task delegated to a Template::Stash object). The localise() and delocalise() methods are provided to handle localisation of the stash.

The context also maintains a reference to a cache of previously compiled templates and has the facility to load, parse and compile new template documents as they are requested. These templates can then be accessed from within other templates via the "INCLUDE template_name" directive or may be rendered by a direct call from a template processing engine. The Template::Cache manages the template documents for the context and delegates the parsing of new templates to a Template::Parser object. A cache may be shared among multiple context objects allowing common templates documents to be compile only once and rendered many times in different contexts.

In addition, the context provides facilities for loading plugins and filters.

The context object provides template output and error handling methods which can output/delegate to a user-supplied file handle, text string or sub-routine. These handlers are defined using the redirect() method.

PUBLIC METHODS

new(\%config)

Constructor method which instantiates a new Template::Context object, initialised with the contents of an optional configuration hash array passed by reference as a parameter.

Valid configuration values are:

CATCH

The CATCH option may be used to specify a hash array of error handlers.

STASH

A reference to a Template::Stash object or derivative which should be used for storing and managing variable data. A default stash is created (using PRE_DEFINE variables) if this parameter is not defined.

PRE_DEFINE

A reference to a hash which is passed to the Stash constructor to pre-defined variables. This variable has no effect if STASH is defined to contain some existing Stash object.

PRE_PROCESS/POST_PROCESS

The PRE_PROCESS and POST_PROCESS options can be used to define templates that should be processed immediately before and after each template processed by the process() option, respectively. The templates are processed in the same variable context as the main template. The PRE_PROCESS can be used to define variables that might then be used in the main template, for example.

Any uncaught exceptions raised in the PRE/POST_PROCESS templates are ignored.

CACHE

A reference to a Template::Cache object or derivative which should be used for loading, parsing, compiling and caching template documents. A default cache is created (passing all configuration parameters) if this is not provided.

process($template, \%params)

The process() method is called to render a template document within the current context. The first parameter should name the template document or should be a file handle, glob reference or string (scalar) reference from which the template can be read. The second, optional parameter should be a reference to a hash array of variables and values that should be defined for use (i.e. substitution) within the template.

    my $params = {
        'name' = 'Fred Oliver Oscarson',
        'id'   = 'foo'
    };

    $context->process('foopage.html', $params);

redirect($what, $where)

The redirect() method should be called with a first parameter represented by one of the constants TEMPLATE_OUTPUT or TEMPLATE_ERROR. These are defined in Template::Constants and can be imported by specifying ':template' as a parameter to use Template or use Template::Constants.

The second parameter may contain a file handle (GLOB or IO::handle) to which the output or error stream should be written. Altenatively, $where may be a reference to a scalar variable to which output is appended or a code reference which is called to handle output.

    use Template::Context;
    use Template::Constants qw( :template );

    my $context = Template::Context->new();
    my $output  = '';
    $context->redirect(TEMPLATE_OUTPUT, \$output);
    $context->redirect(TEMPLATE_ERROR, \*STDOUT);

output($text, ...)

Prints all passed parameters to the output stream for the current template context. By default, output is sent to STDOUT unless redirected by calling the redirect() method.

    $context->output("The cat sat on the ", $place);

error($text, ...)

Directs the passed parameters to the error stream for the current template context. By default, errors are sent to STDERR unless redirected by calling the redirect() method.

    $context->error("This parrot is ", $dead);

throw($type, $info) / throw($exception)

The throw() method is called by other Template modules when an error condition occurs. The caller will pass an error type and information string or a reference to a Template::Exception which encompasses those values. The error type is used to index into the CATCH hash array to see if a handler has been defined for this kind of error. If it has, the CATCH value is returned or code reference is run and it's value returned.

catch($type, $handler)

The catch() method is used to install an exception handler for a specific type of error.

use_plugin($name, \@params)

Called to load, instantiate and return an instance of a plugin object.

use_filter($name, \@params, $alias)

Called to load, instaniate and return a filter sub-routine.

AUTHOR

Andy Wardley <cre.canon.co.uk>

REVISION

$Revision: 1.24 $

COPYRIGHT

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

SEE ALSO

Template

cpanm Template

perl -MCPAN -e shell
install Template