: | new(), init(), acquire(), release(), release_all(), facility(), facilities(), engage(), disengage(), switch() |
sub my_template_code { my $context = shift; ... }
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):
[% # explicit CONTEXT switch CONTEXT splash; INCLUDE button content='Hello World'; # ...other template code executed in splash context... # switch back to default CONTEXT CONTEXT default %] [% # specify CONTEXT on a per-directive basis INCLUDE button content='Hello World' CONTEXT='splash' %] [% # context facilities may define directives that implicitly # change context SPLASH button content='Hello World' %] [% # access context facilities directly splash.view.button(context='Hello World') %] [% # access any additional context methods defined splash.button(context='Hello World') %]
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.
$context = $context->switch('splash');
new( \%vars )
Constructor method implemented by Template::Base.
init( \%config )
Initialiser method called by base class new() constructor method.
acquire( $name, $facility, \@args )
Method called to have the context acquire a facility by calling
the acquire()
method
against the $facility()
reference, passing $self
as a reference and any
additional arguments passed. The method then stores the
$facility() reference
in the internal _FACILITY
hash index by $name
.
Returns 1 on success. Returns undef on error and sets an
appropriate error message, accessible via the error()
method.
release( $name )
Releases the facility indexed in the internal
_FACILITY
hash by calling its release()
method and then
deleting the entry from the _FACILITY
hash. This
breaks the circular reference between the context and facility.
Returns 1 on success. Returns undef on error and sets an
appropriate error message, accessible via the error()
method.
release_all()
Releases all the facilities currently acquired by the context.
Returns 1 on success. Returns undef on error and sets an
appropriate error message, accessible via the error()
method.
Returns a reference to the facility currently acquired under the
name passed as an argument. Returns undef if the facility is not
defined and sets an appropriate error message, accessible via the
error()
method.
facilities( )
facilities( $name, $name, ... )
Returns a reference to the internal _FACILITY
hash
when called without any arguments. When called in list context
with one or more arguments, it returns a list of the facilities as
per facility()
. When called in scalar context it
returns a reference to the same list. Returns undef if any of the
facilities are not defined and sets an appropriate error message,
accessible via the error()
method.
engage( $service, @args )
Engage the context for use with a service.
disengage( $service, @args )
Disengage the context from use with a service.
switch( $name, @args )
Switch to a new context.