Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Template::Context(3)  User Contributed Perl Documentation Template::Context(3)

       Template::Context - Runtime context in which templates are processed

	   use Template::Context;

	   # constructor
	   $context = Template::Context->new(\%config)
	       || die $Template::Context::ERROR;

	   # fetch (load and compile) a	template
	   $template = $context->template($template_name);

	   # fetch (load and instantiate) a plugin object
	   $plugin = $context->plugin($name, \@args);

	   # fetch (return or create) a	filter subroutine
	   $filter = $context->filter($name, \@args, $alias);

	   # process/include a template, errors	are thrown via die()
	   $output = $context->process($template, \%vars);
	   $output = $context->include($template, \%vars);

	   # raise an exception	via die()
	   $context->throw($error_type,	$error_message,	\$output_buffer);

	   # catch an exception, clean it up and fix output buffer
	   $exception =	$context->catch($exception, \$output_buffer);

	   # save/restore the stash to effect variable localisation
	   $new_stash =	$context->localise(\%vars);
	   $old_stash =	$context->delocalise();

	   # add new BLOCK or FILTER definitions
	   $context->define_block($name, $block);
	   $context->define_filter($name, \&filtersub, $is_dynamic);

	   # reset context, clearing any imported BLOCK	definitions

	   # methods for accessing internal items
	   $stash     =	$context->stash();
	   $tflag     =	$context->trim();
	   $epflag    =	$context->eval_perl();
	   $providers =	$context->templates();
	   $providers =	$context->plugins();
	   $providers =	$context->filters();

       The "Template::Context" module defines an object	class for representing
       a runtime context in which templates are	processed.  It provides	an
       interface to the	fundamental operations of the Template Toolkit
       processing engine through which compiled	templates (i.e.	Perl code
       constructed from	the template source) can process templates, load
       plugins and filters, raise exceptions and so on.

       A default "Template::Context" object is created by the Template module.
       Any "Template::Context" options may be passed to	the Template new()
       constructor method and will be forwarded	to the "Template::Context"

	   use Template;

	   my $template	= Template->new({
	       TRIM	 => 1,
	       EVAL_PERL => 1,
	       BLOCKS	 => {
		   header => 'This is the header',
		   footer => 'This is the footer',

       Similarly, the "Template::Context" constructor will forward all
       configuration parameters	onto other default objects (e.g.
       Template::Provider, Template::Plugins, Template::Filters, etc.) that it
       may need	to instantiate.

	   $context = Template::Context->new({
	       INCLUDE_PATH => '/home/abw/templates', #	provider option
	       TAG_STYLE    => 'html',		      #	parser option

       A "Template::Context" object (or	subclass) can be explicitly
       instantiated and	passed to the Template new() constructor method	as the
       "CONTEXT" configuration item.

	   use Template;
	   use Template::Context;

	   my $context	= Template::Context->new({ TRIM	=> 1 });
	   my $template	= Template->new({ CONTEXT => $context });

       The Template module uses	the Template::Config context() factory method
       to create a default context object when required. The
       $Template::Config::CONTEXT package variable may be set to specify an
       alternate context module. This will be loaded automatically and its
       new() constructor method	called by the context()	factory	method when a
       default context object is required.

	   use Template;

	   $Template::Config::CONTEXT =	'MyOrg::Template::Context';

	   my $template	= Template->new({
	       EVAL_PERL   => 1,
	       EXTRA_MAGIC => 'red hot',  # your extra config items

       The "new()" constructor method is called	to instantiate a
       "Template::Context" object. Configuration parameters may	be specified
       as a HASH reference or as a list	of "name => value" pairs.

	   my $context = Template::Context->new({
	       INCLUDE_PATH => 'header',
	       POST_PROCESS => 'footer',

	   my $context = Template::Context->new( EVAL_PERL => 1	);

       The "new()" method returns a "Template::Context"	object or "undef" on
       error. In the latter case, a relevant error message can be retrieved by
       the error() class method	or directly from the $Template::Context::ERROR
       package variable.

	   my $context = Template::Context->new(\%config)
	       || die Template::Context->error();

	   my $context = Template::Context->new(\%config)
	       || die $Template::Context::ERROR;

       The following configuration items may be	specified.  Please see
       Template::Manual::Config	for further details.


       The VARIABLES option can	be used	to specify a hash array	of template

	   my $context = Template::Context->new({
	       VARIABLES => {
		   title   => 'A Demo Page',
		   author  => 'Joe Random Hacker',
		   version => 3.14,


       The BLOCKS option can be	used to	pre-define a default set of template

	   my $context = Template::Context->new({
	       BLOCKS => {
		   header  => 'The Header.  [% title %]',
		   footer  => sub { return $some_output_text },
		   another => Template::Document->new({	... }),


       The VIEWS option	can be used to pre-define one or more Template::View

	   my $context = Template::Context->new({
	       VIEWS =>	[
		   bottom => { prefix => 'bottom/' },
		   middle => { prefix => 'middle/', base => 'bottom' },
		   top	  => { prefix => 'top/',    base => 'middle' },


       The TRIM	option can be set to have any leading and trailing whitespace
       automatically removed from the output of	all template files and


	   [% BLOCK foo	%]

	   Line	1 of foo

	   [% END %]

	   [% INCLUDE foo %]


	   Line	1 of foo


       The EVAL_PERL is	used to	indicate if "PERL" and/or "RAWPERL" blocks
       should be evaluated. It is disabled by default.


       The RECURSION can be set	to allow templates to recursively process
       themselves, either directly (e.g. template "foo"	calls "INCLUDE foo")
       or indirectly (e.g.  "foo" calls	"INCLUDE bar" which calls "INCLUDE


       The LOAD_TEMPLATES option can be	used to	provide	a reference to a list
       of Template::Provider objects or	sub-classes thereof which will take
       responsibility for loading and compiling	templates.

	   my $context = Template::Context->new({
	       LOAD_TEMPLATES => [
		   MyOrg::Template::Provider->new({ ...	}),
		   Template::Provider->new({ ... }),


       The LOAD_PLUGINS	options	can be used to specify a list of provider
       objects responsible for loading and instantiating template plugin

	   my $context = Template::Context->new({
	       LOAD_PLUGINS => [
		   MyOrg::Template::Plugins->new({ ... }),
		   Template::Plugins->new({ ...	}),


       The LOAD_FILTERS	option can be used to specify a	list of	provider
       objects for returning and/or creating filter subroutines.

	   my $context = Template::Context->new({
	       LOAD_FILTERS => [


       The STASH option	can be used to specify a Template::Stash object	or
       sub-class which will take responsibility	for managing template

	   my $stash = MyOrg::Template::Stash->new({ ... });
	   my $context = Template::Context->new({
	       STASH =>	$stash,


       The DEBUG option	can be used to enable various debugging	features of
       the Template::Context module.

	   use Template::Constants qw( :debug );

	   my $template	= Template->new({

       Returns a compiled template by querying each of the LOAD_TEMPLATES
       providers (instances of Template::Provider, or sub-class) in turn.

	   $template = $context->template('header');

       On error, a Template::Exception object of type '"file"' is thrown via
       "die()".	 This can be caught by enclosing the call to "template()" in
       an "eval" block and examining $@.

	   eval	{ $template = $context->template('header') };
	   if ($@) {
	       print "failed to	fetch template:	$@\n";

   plugin($name, \@args)
       Instantiates a plugin object by querying	each of	the LOAD_PLUGINS
       providers. The default LOAD_PLUGINS provider is a Template::Plugins
       object which attempts to	load plugin modules, according the various
       configuration items such	as PLUGIN_BASE,	LOAD_PERL, etc., and then
       instantiate an object via new().	A reference to a list of constructor
       arguments may be	passed as the second parameter.	These are forwarded to
       the plugin constructor.

       Returns a reference to a	plugin (which is generally an object, but
       doesn't have to be).  Errors are	thrown as Template::Exception objects
       with the	type set to '"plugin"'.

	   $plugin = $context->plugin('DBI', 'dbi:msql:mydbname');

   filter($name, \@args, $alias)
       Instantiates a filter subroutine	by querying the	LOAD_FILTERS
       providers.  The default LOAD_FILTERS provider is	a Template::Filters

       Additional arguments may	be passed by list reference along with an
       optional	alias under which the filter will be cached for	subsequent
       use. The	filter is cached under its own $name if	$alias is undefined.
       Subsequent calls	to "filter($name)" will	return the cached entry, if
       defined.	Specifying arguments bypasses the caching mechanism and	always
       creates a new filter. Errors are	thrown as Template::Exception objects
       with the	type set to '"filter"'.

	   # static filter (no args)
	   $filter = $context->filter('html');

	   # dynamic filter (args) aliased to 'padright'
	   $filter = $context->filter('format',	'%60s',	'padright');

	   # retrieve previous filter via 'padright' alias
	   $filter = $context->filter('padright');

   process($template, \%vars)
       Processes a template named or referenced	by the first parameter and
       returns the output generated.  An optional reference to a hash array
       may be passed as	the second parameter, containing variable definitions
       which will be set before	the template is	processed.  The	template is
       processed in the	current	context, with no localisation of variables
       performed.   Errors are thrown as Template::Exception objects via

	   $output = $context->process('header', { title => 'Hello World' });

   include($template, \%vars)
       Similar to process(), but using localised variables.  Changes made to
       any variables will only persist until the "include()" method completes.

	   $output = $context->include('header', { title => 'Hello World' });

       This method returns the source content of a template file without
       performing any evaluation.  It is used to implement the "INSERT"

   throw($error_type, $error_message, \$output)
       Raises an exception in the form of a Template::Exception	object by
       calling "die()".	This method may	be passed a reference to an existing
       Template::Exception object; a single value containing an	error message
       which is	used to	instantiate a Template::Exception of type '"undef"';
       or a pair of values representing	the exception "type" and "info"	from
       which a Template::Exception object is instantiated. e.g.

	   $context->throw("I'm	sorry Dave, I can't do that");
	   $context->throw('denied', "I'm sorry	Dave, I	can't do that");

       The optional third parameter may	be a reference to the current output
       buffer.	This is	then stored in the exception object when created,
       allowing	the catcher to examine and use the output up to	the point at
       which the exception was raised.

	   $output .= 'blah blah blah';
	   $output .= 'more rhubarb';
	   $context->throw('yack', 'Too	much yacking', \$output);

   catch($exception, \$output)
       Catches an exception thrown, either as a	reference to a
       Template::Exception object or some other	value. In the latter case, the
       error string is promoted	to a Template::Exception object	of '"undef"'
       type. This method also accepts a	reference to the current output	buffer
       which is	passed to the Template::Exception constructor, or is appended
       to the output buffer stored in an existing Template::Exception object,
       if unique (i.e. not the same reference).	By this	process, the correct
       state of	the output buffer can be reconstructed for simple or nested

   define_block($name, $block)
       Adds a new block	definition to the internal BLOCKS cache.  The first
       argument	should contain the name	of the block and the second a
       reference to a Template::Document object	or template sub-routine, or
       template	text which is automatically compiled into a template sub-

       Returns a true value (the sub-routine or	Template::Document reference)
       on success or undef on failure. The relevant error message can be
       retrieved by calling the	error()	method.

   define_filter($name,	\&filter, $is_dynamic)
       Adds a new filter definition by calling the store() method on each of
       the LOAD_FILTERS	providers until	accepted (in the usual case, this is
       accepted	straight away by the one and only Template::Filters provider).
       The first argument should contain the name of the filter	and the	second
       a reference to a	filter subroutine. The optional	third argument can be
       set to any true value to	indicate that the subroutine is	a dynamic
       filter factory.

       Returns a true value or throws a	'"filter"' exception on	error.

   define_vmethod($type, $name,	$code)
       This method is a	wrapper	around the Template::Stash define_vmethod()
       method.	It can be used to define new virtual methods.

	   # define a new scalar (item)	virtual	method
	       item => ucfirst => sub {
		   my $text = shift;
		   return ucfirst $text;

   define_view($name, \%params)
       This method allows you to define	a named	view.

	       my_view => {
		   prefix => 'my_templates/'

       The view	is then	accessible as a	template variable.

	   [% my_view.print(some_data) %]

       This method allows you to define	multiple named views.  A reference to
       a hash array or list reference should be	passed as an argument.

	   $context->define_view({     # hash reference
	       my_view_one => {
		   prefix => 'my_templates_one/'
	       my_view_two => {
		   prefix => 'my_templates_two/'

       If you're defining multiple views of which one or more are based	on
       other views in the same definition then you should pass them as a list
       reference.  This	ensures	that they get created in the right order (Perl
       does not	preserve the order of items defined in a hash reference	so you
       can't guarantee that your base class view will be defined before	your
       subclass	view).

	   $context->define_view([     # list referenence
	       my_view_one => {
		   prefix => 'my_templates_one/'
	       my_view_two => {
		   prefix => 'my_templates_two/' ,
		   base	  => 'my_view_one',

       The views are then accessible as	template variables.

	   [% my_view_one.print(some_data) %]
	   [% my_view_two.print(some_data) %]

       See also	the VIEWS option.

       This method returns the Template::Stash object used internally to
       manage template variables.

       Clones the stash	to create a context with localised variables.  Returns
       a reference to the newly	cloned stash object which is also stored

	   $stash = $context->localise();

       Restore the stash to its	state prior to localisation.

	   $stash = $context->delocalise();

       This method is called by	Template::Document objects immediately before
       they process their content.  It is called to register any local "BLOCK"
       definitions with	the context object so that they	may be subsequently
       delivered on request.

       Compliment to the visit() method. Called	by Template::Document objects
       immediately after they process their content.

       This method creates a Template::View object bound to the	context.

       Clears the local	BLOCKS cache of	any "BLOCK" definitions.  Any initial
       set of BLOCKS specified as a configuration item to the constructor will
       be reinstated.

   debugging($flag, @args)
       This method is used to control debugging	output.	 It is used to
       implement the DEBUG directive.

       The first argument can be "on" or "off" to enable or disable debugging
       respectively.  The numerical values 0 and 1 can also be used if you


       Alternately, the	first argument can be "format" to define a new debug
       message format.	The second argument should be the format string	which
       can contain any of the $file, $line or $text symbols to indicate	where
       the relevant values should be inserted.

	   # note single quotes	to prevent interpolated	of variables
	   $context->debugging(	format => '## $file line $line:	$text' );

       The final use of	this method is to generate debugging messages
       themselves.  The	first argument should be "msg",	followed by a
       reference to a hash array of value to insert into the debugging format

	       msg => {
		   line	=> 20,
		   file	=> '',
		   text	=> 'Trampoline!	Trampoline!',

       An "AUTOLOAD" method provides access to context configuration items.

	   $stash     =	$context->stash();
	   $tflag     =	$context->trim();
	   $epflag    =	$context->eval_perl();

       Andy Wardley <> <>

       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.

       Template, Template::Document, Template::Exception, Template::Filters,
       Template::Plugins, Template::Provider, Template::Service,

perl v5.32.1			  2020-07-13		  Template::Context(3)


Want to link to this manual page? Use this URL:

home | help