Template Toolkit Version 3 Developer Documentation
http://www.template-toolkit.org/v3/

Template::Context

Table of Contents

: new()init()acquire()release()release_all()facility()facilities()engage()disengage()switch()

Synopsis


Description

The Template::Context module implements a class of objects which are used to represent a runtime context for processing templates. In previous versions of the Template Toolkit the Context implemented various methods that the compiled Perl template code could call to access core toolkit functionality, e.g. include(), plugin(), filter(), etc.

In version 3, the core functionality has been moved out of the context into separate modular sub-systems known as "Facilities". These are all derived from the Template::Facility class and include modules like Template::Stash (variable management), Template::View (template management), Template::Plugins (plugin management), Template::Filters (filter management), and so on.

Each Context object can hold references to any number of different facilities, each of which must be identified by a unique name (e.g. 'stash', 'view', 'plugins', 'filters'). The acquire() can be used to bind a facility to a Context object, the release() method can be called to subsequently release it. When a Context acquires a facility it calls the acquire() method of the $facility object, passing itself as a reference for the facility to store. The facility can then use the context reference at a later time to access other facilities that it may require to perform its task.

Note that this creates a circular reference between the context and facility. The release() is thus provided for a context to release a facility from a context. This calls the release() method of the facility which destroys its reference to the context. The context then destroys its reference to the facility. The vicious circle is thus broken allowing Perl to fully garbage collect the context and facility at the appropriate time. All is again well with the Universe.

The facility() method can be used to access a currently acquired facility held by a context. The facilities() method can be used to fetch one or more facility references en masse.

Another new feature in version 3 is the ability to define multiple contexts each of which has its own set of facilities describing the Template Toolkit features available within it. You can switch between contexts or specify that a template be processed in a particular context in various different ways (yet to be finalised):

Contexts may share facilities or share components within a faclility. For example, two different contexts may share the same view facility, or they might have different views that share a common template provider. Or contexts may define their own independant facilities. For example, the 'splash' context might define it's own stash to ensure that any variables it defines are totally separated from any user variables in other contexts.

The Template::Service module defines the object class which keeps track of the contexts defined. It calls the engage() method on a context object when it is switched in for use and subsequently calls the disengage() method when the context is switched out. In each case, a reference to the service object is passed which the context stores internally.

The switch() method can be called against a currently engaged context object to switch to another context defined by the parent Template::Service object. The method fetches the new context from the service via the context() method which then disengages the current context and engages the new context. The switch() method then returns a reference to the newly engaged context.


Methods

Template Toolkit Version 3 Developer Documentation
http://www.template-toolkit.org/v3/