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

FreeBSD Manual Pages

  
 
  

home | help
Template::Manual::ConfUser)Contributed Perl DocumenTemplate::Manual::Config(3)

NAME
       Template::Manual::Config	- Configuration	options

Template Style and Parsing Options
   ENCODING
       The "ENCODING" option specifies the template files' character encoding:

	   my $template	= Template->new({
	       ENCODING	=> 'utf8',
	   });

       A template which	starts with a Unicode byte order mark (BOM) will have
       its encoding detected automatically.

   START_TAG, END_TAG
       The "START_TAG" and "END_TAG" options are used to specify character
       sequences or regular expressions	that mark the start and	end of inline
       template	directives.  The default values	for "START_TAG"	and "END_TAG"
       are '"[%"' and '"%]"' respectively, giving us the familiar directive
       style:

	   [% example %]

       Any Perl	regex characters can be	used and therefore should be escaped
       (or use the Perl	"quotemeta" function) if they are intended to
       represent literal characters.

	   my $template	= Template->new({
	       START_TAG => quotemeta('<+'),
	       END_TAG	 => quotemeta('+>'),
	   });

       Example:

	   <+ INCLUDE foobar +>

       The "TAGS" directive can	also be	used to	set the	"START_TAG" and
       "END_TAG" values	on a per-template file basis.

	   [% TAGS <+ +> %]

   OUTLINE_TAG
       The "OUTLINE_TAG" option	can be used to enable single-line "outline"
       directives.

	   my $template	= Template->new({
	       OUTLINE_TAG => '%%',
	   });

       This allows you to use both inline and outline tags like	so:

	   %% IF user
	   Hello [% user.name %]
	   %% END

       The "OUTLINE_TAG" string	(or regex) must	appear at the start of a line.
       The directive continues until the end of	the line.  The newline
       character at the	end of the line	is considered to be the	invisible end-
       of-directive marker and is removed.

   TAG_STYLE
       The "TAG_STYLE" option can be used to set both "START_TAG" and
       "END_TAG" according to pre-defined tag styles.

	   my $template	= Template->new({
	       TAG_STYLE => 'star',
	   });

       Available styles	are:

	   template    [% ... %]	       (default)
	   template1   [% ... %] or %% ... %%  (TT version 1)
	   metatext    %% ... %%	       (Text::MetaText)
	   star	       [* ... *]	       (TT alternate)
	   php	       <? ... ?>	       (PHP)
	   asp	       <% ... %>	       (ASP)
	   mason       <% ...  >	       (HTML::Mason)
	   html	       <!-- ...	-->	       (HTML comments)

       The "outline" style uses	the default markers for	"START_TAG" and
       "END_TAG" ("[%" and "%]"	respectively) and additionally defines
       "OUTLINE_TAG" to	be "%%".

	   my $template	= Template->new({
	       TAG_STYLE => 'outline',
	   });

       This allows you to use both inline and outline tags like	so:

	   %% IF user
	   Hello [% user.name %]
	   %% END

       Any values specified for	"START_TAG", "END_TAG" and/or "OUTLINE_TAG"
       will override those defined by a	"TAG_STYLE".

       The "TAGS" directive may	also be	used to	set a "TAG_STYLE"

	   [% TAGS html	%]
	   <!--	INCLUDE	header -->

   PRE_CHOMP, POST_CHOMP
       Anything	outside	a directive tag	is considered plain text and is
       generally passed	through	unaltered (but see the INTERPOLATE option).
       This includes all whitespace and	newlines characters surrounding
       directive tags.	Directives that	don't generate any output will leave
       gaps in the output document.

       Example:

	   Foo
	   [% a	= 10 %]
	   Bar

       Output:

	   Foo

	   Bar

       The "PRE_CHOMP" and "POST_CHOMP"	options	can help to clean up some of
       this extraneous whitespace.  Both are disabled by default.

	   my $template	= Template->new({
	       PRE_CHOMP  => 1,
	       POST_CHOMP => 1,
	   });

       With "PRE_CHOMP"	set to 1, the newline and whitespace preceding a
       directive at the	start of a line	will be	deleted.  This has the effect
       of concatenating	a line that starts with	a directive onto the end of
       the previous line.

	       Foo <----------.
			      |
	   ,---(PRE_CHOMP)----'
	   |
	   `-- [% a = 10 %] --.
			      |
	   ,---(POST_CHOMP)---'
	   |
	   `-> Bar

       With "POST_CHOMP" set to	1, any whitespace after	a directive up to and
       including the newline will be deleted.  This has	the effect of joining
       a line that ends	with a directive onto the start	of the next line.

       If "PRE_CHOMP" or "POST_CHOMP" is set to	2, all whitespace including
       any number of newline will be removed and replaced with a single	space.
       This is useful for HTML,	where (usually)	a contiguous block of
       whitespace is rendered the same as a single space.

       With "PRE_CHOMP"	or "POST_CHOMP"	set to 3, all adjacent whitespace
       (including newlines) will be removed entirely.

       These values are	defined	as "CHOMP_NONE", "CHOMP_ONE", "CHOMP_COLLAPSE"
       and "CHOMP_GREEDY" constants in the Template::Constants module.
       "CHOMP_ALL" is also defined as an alias for "CHOMP_ONE" to provide
       backwards compatibility with earlier version of the Template Toolkit.

       Additionally the	chomp tag modifiers listed below may also be used for
       the "PRE_CHOMP" and "POST_CHOMP"	configuration.

	    my $template = Template->new({
	       PRE_CHOMP  => '~',
	       POST_CHOMP => '-',
	    });

       "PRE_CHOMP" and "POST_CHOMP" can	be activated for individual directives
       by placing a '"-"' immediately at the start and/or end of the
       directive.

	   [% FOREACH user IN userlist %]
	      [%- user -%]
	   [% END %]

       This has	the same effect	as "CHOMP_ONE" in removing all whitespace
       before or after the directive up	to and including the newline.  The
       template	will be	processed as if	written:

	   [% FOREACH user IN userlist %][% user %][% END %]

       To remove all whitespace	including any number of	newlines, use the
       ('"~"') tilde character instead.

	   [% FOREACH user IN userlist %]

	      [%~ user ~%]

	   [% END %]

       To collapse all whitespace to a single space, use the '"="' equals sign
       character.

	   [% FOREACH user IN userlist %]

	      [%= user =%]

	   [% END %]

       Here the	template is processed as if written:

	   [% FOREACH user IN userlist %] [% user %] [%	END %]

       If you have "PRE_CHOMP" or "POST_CHOMP" set as configuration options
       then you	can use	the '"+"' plus sign to disable any chomping options
       (i.e. leave the whitespace intact) on a per-directive basis.

	   [% FOREACH user IN userlist %]
	   User: [% user +%]
	   [% END %]

       With "POST_CHOMP" set to	"CHOMP_ONE", the above example would be	parsed
       as if written:

	   [% FOREACH user IN userlist %]User: [% user %]
	   [% END %]

       For reference, the "PRE_CHOMP" and "POST_CHOMP" configuration options
       may be set to any of the	following:

	    Constant	  Value	  Tag Modifier
	    ----------------------------------
	    CHOMP_NONE	    0	       +
	    CHOMP_ONE	    1	       -
	    CHOMP_COLLAPSE  2	       =
	    CHOMP_GREEDY    3	       ~

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

       By example, the following "BLOCK" definition

	   [% BLOCK foo	%]
	   Line	1 of foo
	   [% END %]

       will be processed is as ""\nLine	1 of foo\n"".  When "INCLUDE"d,	the
       surrounding newlines will also be introduced.

	   before
	   [% INCLUDE foo %]
	   after

       Generated output:

	   before

	   Line	1 of foo

	   after

       With the	"TRIM" option set to any true value, the leading and trailing
       newlines	(which count as	whitespace) will be removed from the output of
       the "BLOCK".

	   before
	   Line	1 of foo
	   after

       The "TRIM" option is disabled (0) by default.

   INTERPOLATE
       The "INTERPOLATE" flag, when set	to any true value will cause variable
       references in plain text	(i.e. not surrounded by	"START_TAG" and
       "END_TAG") to be	recognised and interpolated accordingly.

	   my $template	= Template->new({
	       INTERPOLATE => 1,
	   });

       Variables should	be prefixed by a '"$"' dollar sign to identify them.
       Curly braces '"{"' and '"}"' can	be used	in the familiar	Perl/shell
       style to	explicitly scope the variable name where required.

	   # INTERPOLATE => 0
	   <a href="http://[% server %]/[% help	%]">
	   <img	src="[%	images %]/help.gif"></a>
	   [% myorg.name %]

	   # INTERPOLATE => 1
	   <a href="http://$server/$help">
	   <img	src="$images/help.gif"></a>
	   $myorg.name

	   # explicit scoping with {  }
	   <img	src="$images/${icon.next}.gif">

       Note that a limitation in Perl's	regex engine restricts the maximum
       length of an interpolated template to around 32 kilobytes or possibly
       less.  Files that exceed	this limit in size will	typically cause	Perl
       to dump core with a segmentation	fault.	If you routinely process
       templates of this size then you should disable "INTERPOLATE" or split
       the templates in	several	smaller	files or blocks	which can then be
       joined backed together via "PROCESS" or "INCLUDE".

   ANYCASE
       By default, directive keywords should be	expressed in UPPER CASE.  The
       "ANYCASE" option	can be set to allow directive keywords to be specified
       in any case.

	   # ANYCASE =>	0 (default)
	   [% INCLUDE foobar %]	       # OK
	   [% include foobar %]	       # ERROR
	   [% include =	10   %]	       # OK, 'include' is a variable

	   # ANYCASE =>	1
	   [% INCLUDE foobar %]	       # OK
	   [% include foobar %]	       # OK
	   [% include =	10   %]	       # ERROR,	'include' is reserved word

       One side-effect of enabling "ANYCASE" is	that you cannot	use a variable
       of the same name	as a reserved word, regardless of case.	 The reserved
       words are currently:

	   GET CALL SET	DEFAULT	INSERT INCLUDE PROCESS WRAPPER
	   IF UNLESS ELSE ELSIF	FOR FOREACH WHILE SWITCH CASE
	   USE PLUGIN FILTER MACRO PERL	RAWPERL	BLOCK META
	   TRY THROW CATCH FINAL NEXT LAST BREAK RETURN	STOP
	   CLEAR TO STEP AND OR	NOT MOD	DIV END

       The only	lower case reserved words that cannot be used for variables,
       regardless of the "ANYCASE" option, are the operators:

	   and or not mod div

Template Files and Blocks
   INCLUDE_PATH
       The "INCLUDE_PATH" is used to specify one or more directories in	which
       template	files are located.  When a template is requested that isn't
       defined locally as a "BLOCK", each of the "INCLUDE_PATH"	directories is
       searched	in turn	to locate the template file.  Multiple directories can
       be specified as a reference to a	list or	as a single string where each
       directory is delimited by the '":"' colon character.

	   my $template	= Template->new({
	       INCLUDE_PATH => '/usr/local/templates',
	   });

	   my $template	= Template->new({
	       INCLUDE_PATH => '/usr/local/templates:/tmp/my/templates',
	   });

	   my $template	= Template->new({
	       INCLUDE_PATH => [ '/usr/local/templates',
				 '/tmp/my/templates' ],
	   });

       On Win32	systems, a little extra	magic is invoked, ignoring delimiters
       that have '":"' colon followed by a '"/"' slash or '"\"'	blackslash.
       This avoids confusion when using	directory names	like '"C:\Blah Blah"'.

       When specified as a list, the "INCLUDE_PATH" path can contain elements
       which dynamically generate a list of "INCLUDE_PATH" directories.	 These
       generator elements can be specified as a	reference to a subroutine or
       an object which implements a "paths()" method.

	   my $template	= Template->new({
	       INCLUDE_PATH => [ '/usr/local/templates',
				 \&incpath_generator,
				 My::IncPath::Generator->new( ... ) ],
	   });

       Each time a template is requested and the "INCLUDE_PATH"	examined, the
       subroutine or object method will	be called.  A reference	to a list of
       directories should be returned.	Generator subroutines should report
       errors using "die()".  Generator	objects	should return undef and	make
       an error	available via its "error()" method.

       For example:

	   sub incpath_generator {
	       # ...some code...

	       if ($all_is_well) {
		   return \@list_of_directories;
	       }
	       else {
		   die "cannot generate	INCLUDE_PATH...\n";
	       }
	   }

       or:

	   package My::IncPath::Generator;

	   # Template::Base (or	Class::Base) provides error() method
	   use Template::Base;
	   use base qw(	Template::Base );

	   sub paths {
	       my $self	= shift;

	       # ...some code...

	       if ($all_is_well) {
		   return \@list_of_directories;
	       }
	       else {
		   return $self->error("cannot generate	INCLUDE_PATH...\n");
	       }
	   }

	   1;

   DELIMITER
       Used to provide an alternative delimiter	character sequence for
       separating paths	specified in the "INCLUDE_PATH".  The default value
       for "DELIMITER" is the '":"' colon character.

	   my $template	= Template->new({
	       DELIMITER    => '; ',
	       INCLUDE_PATH => 'C:/HERE/NOW; D:/THERE/THEN',
	   });

       On Win32	systems, the default delimiter is a little more	intelligent,
       splitting paths only on '":"' colon characters that aren't followed by
       a '"/"' slash character.	 This means that the following should work as
       planned,	splitting the "INCLUDE_PATH" into 2 separate directories,
       "C:/foo"	and "C:/bar".

	   # on	Win32 only
	   my $template	= Template->new({
	       INCLUDE_PATH => 'C:/Foo:C:/Bar'
	   });

       However,	if you're using	Win32 then it's	recommended that you
       explicitly set the "DELIMITER" character	to something else (e.g.	'";"'
       semicolon) rather than rely on this subtle magic.

   ABSOLUTE
       The "ABSOLUTE" flag is used to indicate if templates specified with
       absolute	filenames (e.g.	'"/foo/bar"') should be	processed.  It is
       disabled	by default and any attempt to load a template by such a	name
       will cause a '"file"' exception to be raised.

	   my $template	= Template->new({
	       ABSOLUTE	=> 1,
	   });

	   # this is why it's disabled by default
	   [% INSERT /etc/passwd %]

       On Win32	systems, the regular expression	for matching absolute
       pathnames is tweaked slightly to	also detect filenames that start with
       a driver	letter and colon, such as:

	   C:/Foo/Bar

   RELATIVE
       The "RELATIVE" flag is used to indicate if templates specified with
       filenames relative to the current directory (e.g. '"./foo/bar"' or
       '"../../some/where/else"') should be loaded.  It	is also	disabled by
       default,	and will raise a '"file"' error	if such	template names are
       encountered.

	   my $template	= Template->new({
	       RELATIVE	=> 1,
	   });

	   [% INCLUDE ../logs/error.log	%]

   DEFAULT
       The "DEFAULT" option can	be used	to specify a default template which
       should be used whenever a specified template can't be found in the
       "INCLUDE_PATH".

	   my $template	= Template->new({
	       DEFAULT => 'notfound.html',
	   });

       If a non-existent template is requested through the Template process()
       method, or by an	"INCLUDE", "PROCESS" or	"WRAPPER" directive, then the
       "DEFAULT" template will instead be processed, if	defined. Note that the
       "DEFAULT" template is not used when templates are specified with
       absolute	or relative filenames, or as a reference to a input file
       handle or text string.

   BLOCKS
       The "BLOCKS" option can be used to pre-define a default set of template
       blocks.	These should be	specified as a reference to a hash array
       mapping template	names to template text,	subroutines or
       Template::Document objects.

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

   VIEWS
       The VIEWS option	can be used to define one or more Template::View
       objects.	 They can be specified as a reference to a hash	array or list
       reference.

	   my $template	= Template->new({
	       VIEWS =>	{
		   my_view => {	prefix => 'my_templates/' },
	       },
	   });

       Be aware	of the fact that Perl's	hash array are unordered, so if	you
       want to specify multiple	views of which one or more are based on	other
       views, then you should use a list reference to preserve the order of
       definition.

	   my $template	= Template->new({
	       VIEWS =>	[
		   bottom => { prefix => 'bottom/' },
		   middle => { prefix => 'middle/', base => 'bottom' },
		   top	  => { prefix => 'top/',    base => 'middle' },
	       ],
	   });

   AUTO_RESET
       The "AUTO_RESET"	option is set by default and causes the	local "BLOCKS"
       cache for the Template::Context object to be reset on each call to the
       Template	process() method. This ensures that any	"BLOCK"s defined
       within a	template will only persist until that template is finished
       processing. This	prevents "BLOCK"s defined in one processing request
       from interfering	with other independent requests	subsequently processed
       by the same context object.

       The "BLOCKS" item may be	used to	specify	a default set of block
       definitions for the Template::Context object. Subsequent	"BLOCK"
       definitions in templates	will over-ride these but they will be
       reinstated on each reset	if "AUTO_RESET"	is enabled (default), or if
       the Template::Context reset() method is called.

   RECURSION
       The template processor will raise a file	exception if it	detects	direct
       or indirect recursion into a template.  Setting this option to any true
       value will allow	templates to include each other	recursively.

Template Variables
   VARIABLES
       The "VARIABLES" option (or "PRE_DEFINE" - they're equivalent) can be
       used to specify a hash array of template	variables that should be used
       to pre-initialise the stash when	it is created.	These items are
       ignored if the "STASH" item is defined.

	   my $template	= Template->new({
	       VARIABLES => {
		   title   => 'A Demo Page',
		   author  => 'Joe Random Hacker',
		   version => 3.14,
	       },
	   };

       or

	   my $template	= Template->new({
	       PRE_DEFINE => {
		   title   => 'A Demo Page',
		   author  => 'Joe Random Hacker',
		   version => 3.14,
	       },
	   };

   CONSTANTS
       The "CONSTANTS" option can be used to specify a hash array of template
       variables that are compile-time constants.  These variables are
       resolved	once when the template is compiled, and	thus don't require
       further resolution at runtime.  This results in significantly faster
       processing of the compiled templates and	can be used for	variables that
       don't change from one request to	the next.

	   my $template	= Template->new({
	       CONSTANTS => {
		   title   => 'A Demo Page',
		   author  => 'Joe Random Hacker',
		   version => 3.14,
	       },
	   };

   CONSTANT_NAMESPACE
       Constant	variables are accessed via the "constants" namespace by
       default.

	   [% constants.title %]

       The "CONSTANTS_NAMESPACE" option	can be set to specify an alternate
       namespace.

	   my $template	= Template->new({
	       CONSTANTS => {
		   title   => 'A Demo Page',
		   # ...etc...
	       },
	       CONSTANTS_NAMESPACE => 'const',
	   };

       In this case the	constants would	then be	accessed as:

	   [% const.title %]

   NAMESPACE
       The constant folding mechanism described	above is an example of a
       namespace handler.  Namespace handlers can be defined to	provide
       alternate parsing mechanisms for	variables in different namespaces.

       Under the hood, the Template module converts a constructor
       configuration such as:

	   my $template	= Template->new({
	       CONSTANTS => {
		   title   => 'A Demo Page',
		   # ...etc...
	       },
	       CONSTANTS_NAMESPACE => 'const',
	   };

       into one	like:

	   my $template	= Template->new({
	       NAMESPACE => {
		   const => Template:::Namespace::Constants->new({
		       title   => 'A Demo Page',
		       # ...etc...
		   }),
	       },
	   };

       You can use this	mechanism to define multiple constant namespaces, or
       to install custom handlers of your own.

	   my $template	= Template->new({
	       NAMESPACE => {
		   site	=> Template:::Namespace::Constants->new({
		       title   => "Wardley's Widgets",
		       version => 2.718,
		   }),
		   author => Template:::Namespace::Constants->new({
		       name  =>	'Andy Wardley',
		       email =>	'abw@andywardley.com',
		   }),
		   voodoo => My::Namespace::Handler->new( ... ),
	       },
	   };

       Now you have two	constant namespaces, for example:

	   [% site.title %]
	   [% author.name %]

       as well as your own custom namespace handler installed for the 'voodoo'
       namespace.

	   [% voodoo.magic %]

       See Template::Namespace::Constants for an example of what a namespace
       handler looks like on the inside.

Template Processing Options
       The following options are used to specify any additional	templates that
       should be processed before, after, around or instead of the template
       passed as the first argument to the Template process() method.  These
       options can be perform various useful tasks such	as adding standard
       headers or footers to all pages,	wrapping page output in	other
       templates, pre-defining variables or performing initialisation or
       cleanup tasks, automatically generating page summary information,
       navigation elements, and	so on.

       The task	of processing the template is delegated	internally to the
       Template::Service module	which, unsurprisingly, also has	a process()
       method. Any templates defined by	the "PRE_PROCESS" option are processed
       first and any output generated is added to the output buffer. Then the
       main template is	processed, or if one or	more "PROCESS" templates are
       defined then they are instead processed in turn.	In this	case, one of
       the "PROCESS" templates is responsible for processing the main
       template, by a directive	such as:

	   [% PROCESS $template	%]

       The output of processing	the main template or the "PROCESS" template(s)
       is then wrapped in any "WRAPPER"	templates, if defined.	"WRAPPER"
       templates don't need to worry about explicitly processing the template
       because it will have been done for them already.	 Instead "WRAPPER"
       templates access	the content they are wrapping via the "content"
       variable.

	   wrapper before
	   [% content %]
	   wrapper after

       This output generated from processing the main template,	and/or any
       "PROCESS" or "WRAPPER" templates	is added to the	output buffer.
       Finally,	any "POST_PROCESS" templates are processed and their output is
       also added to the output	buffer which is	then returned.

       If the main template throws an exception	during processing then any
       relevant	template(s) defined via	the "ERROR" option will	be processed
       instead.	If defined and successfully processed, the output from the
       error template will be added to the output buffer in place of the
       template	that generated the error and processing	will continue,
       applying	any "WRAPPER" and "POST_PROCESS" templates. If no relevant
       "ERROR" option is defined, or if	the error occurs in one	of the
       "PRE_PROCESS", "WRAPPER"	or "POST_PROCESS" templates, then the process
       will terminate immediately and the error	will be	returned.

   PRE_PROCESS,	POST_PROCESS
       These values may	be set to contain the name(s) of template files
       (relative to "INCLUDE_PATH") which should be processed immediately
       before and/or after each	template.  These do not	get added to templates
       processed into a	document via directives	such as	"INCLUDE", "PROCESS",
       "WRAPPER" etc.

	   my $template	= Template->new({
	       PRE_PROCESS  => 'header',
	       POST_PROCESS => 'footer',
	   };

       Multiple	templates may be specified as a	reference to a list.  Each is
       processed in the	order defined.

	   my $template	= Template->new({
	       PRE_PROCESS  => [ 'config', 'header' ],
	       POST_PROCESS => 'footer',
	   };

       Alternately, multiple template may be specified as a single string,
       delimited by '":"'.  This delimiter string can be changed via the
       "DELIMITER" option.

	   my $template	= Template->new({
	       PRE_PROCESS  => 'config:header',
	       POST_PROCESS => 'footer',
	   };

       The "PRE_PROCESS" and "POST_PROCESS" templates are evaluated in the
       same variable context as	the main document and may define or update
       variables for subsequent	use.

       config:

	   [% #	set some site-wide variables
	      bgcolor =	'#ffffff'
	      version =	2.718
	   %]

       header:

	   [% DEFAULT title = 'My Funky	Web Site' %]
	   <html>
	     <head>
	       <title>[% title %]</title>
	     </head>
	     <body bgcolor="[% bgcolor %]">

       footer:

	       <hr>
	       Version [% version %]
	     </body>
	   </html>

       The Template::Document object representing the main template being
       processed is available within "PRE_PROCESS" and "POST_PROCESS"
       templates as the	"template" variable.  Metadata items defined via the
       "META" directive	may be accessed	accordingly.

	   $template->process('mydoc.html', $vars);

       mydoc.html:

	   [% META title = 'My Document	Title' %]
	   blah	blah blah
	   ...

       header:

	   <html>
	     <head>
	       <title>[% template.title	%]</title>
	     </head>
	     <body bgcolor="[% bgcolor %]">

   PROCESS
       The "PROCESS" option may	be set to contain the name(s) of template
       files (relative to "INCLUDE_PATH") which	should be processed instead of
       the main	template passed	to the Template	process() method.  This	can be
       used to apply consistent	wrappers around	all templates, similar to the
       use of "PRE_PROCESS" and	"POST_PROCESS" templates.

	   my $template	= Template->new({
	       PROCESS	=> 'content',
	   };

	   # processes 'content' instead of 'foo.html'
	   $template->process('foo.html');

       A reference to the original template is available in the	"template"
       variable.  Metadata items can be	inspected and the template can be
       processed by specifying it as a variable	reference (i.e.	prefixed by
       "$") to an "INCLUDE", "PROCESS" or "WRAPPER" directive.

       content:

	   <html>
	     <head>
	       <title>[% template.title	%]</title>
	     </head>
	     <body>
	   <!--	begin content -->
	   [% PROCESS $template	%]
	   <!--	end content -->
	       <hr>
	       &copy; Copyright	[% template.copyright %]
	     </body>
	   </html>

       foo.html:

	   [% META
	      title	= 'The Foo Page'
	      author	= 'Fred	Foo'
	      copyright	= '2000	Fred Foo'
	   %]
	   <h1>[% template.title %]</h1>
	   Welcome to the Foo Page, blah blah blah

       output:

	   <html>
	     <head>
	       <title>The Foo Page</title>
	     </head>
	     <body>
	   <!--	begin content -->
	   <h1>The Foo Page</h1>
	   Welcome to the Foo Page, blah blah blah
	   <!--	end content -->
	       <hr>
	       &copy; Copyright	2000 Fred Foo
	     </body>
	   </html>

   WRAPPER
       The "WRAPPER" option can	be used	to specify one or more templates which
       should be used to wrap around the output	of the main page template.
       The main	template is processed first (or	any "PROCESS" template(s)) and
       the output generated is then passed as the "content" variable to	the
       "WRAPPER" template(s) as	they are processed.

	   my $template	= Template->new({
	       WRAPPER => 'wrapper',
	   };

	   # process 'foo' then	wrap in	'wrapper'
	   $template->process('foo', { message => 'Hello World!' });

       wrapper:

	   <wrapper>
	   [% content %]
	   </wrapper>

       foo:

	   This	is the foo file!
	   Message: [% message %]

       The output generated from this example is:

	   <wrapper>
	   This	is the foo file!
	   Message: Hello World!
	   </wrapper>

       You can specify more than one "WRAPPER" template	by setting the value
       to be a reference to a list of templates.  The "WRAPPER"	templates will
       be processed in reverse order with the output of	each being passed to
       the next	(or previous, depending	on how you look	at it) as the
       'content' variable.  It sounds complicated, but the end result is that
       it just "Does The Right Thing" to make wrapper templates	nest in	the
       order you specify.

	   my $template	= Template->new({
	       WRAPPER => [ 'outer', 'inner' ],
	   };

	   # process 'foo' then	wrap in	'inner', then in 'outer'
	   $template->process('foo', { message => 'Hello World!' });

       outer:

	   <outer>
	   [% content %]
	   </outer>

       inner:

	   <inner>
	   [% content %]
	   </inner>

       The output generated is then:

	   <outer>
	   <inner>
	   This	is the foo file!
	   Message: Hello World!
	   </inner>
	   </outer>

       One side-effect of the "inside-out" processing of the "WRAPPER"
       configuration item (and also the	"WRAPPER" directive) is	that any
       variables set in	the template being wrapped will	be visible to the
       template	doing the wrapping, but	not the	other way around.

       You can use this	to good	effect in allowing page	templates to set pre-
       defined values which are	then used in the wrapper templates.  For
       example,	our main page template 'foo' might look	like this:

       foo:

	   [% page = {
		  title	   = 'Foo Page'
		  subtitle = 'Everything There is to Know About	Foo'
		  author   = 'Frank Oliver Octagon'
	      }
	   %]

	   <p>
	   Welcome to the page that tells you everything about foo
	   blah	blah blah...
	   </p>

       The "foo" template is processed before the wrapper template meaning
       that the	"page" data structure will be defined for use in the wrapper
       template.

       wrapper:

	   <html>
	     <head>
	       <title>[% page.title %]</title>
	     </head>
	     <body>
	       <h1>[% page.title %]</h1>
	       <h2>[% page.subtitle %]</h1>
	       <h3>by [% page.author %]</h3>
	       [% content %]
	     </body>
	   </html>

       It achieves the same effect as defining "META" items which are then
       accessed	via the	"template" variable (which you are still free to use
       within "WRAPPER"	templates), but	gives you more flexibility in the type
       and complexity of data that you can define.

   ERROR
       The "ERROR" (or "ERRORS"	if you prefer) configuration item can be used
       to name a single	template or specify a hash array mapping exception
       types to	templates which	should be used for error handling.  If an
       uncaught	exception is raised from within	a template then	the
       appropriate error template will instead be processed.

       If specified as a single	value then that	template will be processed for
       all uncaught exceptions.

	   my $template	= Template->new({
	       ERROR =>	'error.html'
	   });

       If the "ERROR" item is a	hash reference the keys	are assumed to be
       exception types and the relevant	template for a given exception will be
       selected.  A "default" template may be provided for the general case.
       Note that "ERROR" can be	pluralised to "ERRORS" if you find it more
       appropriate in this case.

	   my $template	= Template->new({
	       ERRORS => {
		   user	    => 'user/index.html',
		   dbi	    => 'error/database',
		   default  => 'error/default',
	       },
	   });

       In this example,	any "user" exceptions thrown will cause	the
       user/index.html template	to be processed, "dbi" errors are handled by
       error/database and all others by	the error/default template.  Any
       "PRE_PROCESS" and/or "POST_PROCESS" templates will also be applied to
       these error templates.

       Note that exception types are hierarchical and a	"foo" handler will
       catch all "foo.*" errors	(e.g. "foo.bar", "foo.bar.baz")	if a more
       specific	handler	isn't defined.	Be sure	to quote any exception types
       that contain periods to prevent Perl concatenating them into a single
       string (i.e. "user.passwd" is parsed as 'user'.'passwd').

	   my $template	= Template->new({
	       ERROR =>	{
		   'user.login'	 => 'user/login.html',
		   'user.passwd' => 'user/badpasswd.html',
		   'user'	 => 'user/index.html',
		   'default'	 => 'error/default',
	       },
	   });

       In this example,	any template processed by the $template	object,	or
       other templates or code called from within, can raise a "user.login"
       exception and have the service redirect to the user/login.html
       template.  Similarly, a "user.passwd" exception has a specific handling
       template, user/badpasswd.html, while all	other "user" or	"user.*"
       exceptions cause	a redirection to the user/index.html page.  All	other
       exception types are handled by error/default.

       Exceptions can be raised	in a template using the	"THROW"	directive,

	   [% THROW user.login 'no user	id: please login' %]

       or by calling the throw() method	on the current Template::Context
       object,

	   $context->throw('user.passwd', 'Incorrect Password');
	   $context->throw('Incorrect Password');    # type 'undef'

       or from Perl code by calling "die()" with a Template::Exception object,

	   die (Template::Exception->new('user.denied',	'Invalid User ID'));

       or by simply calling die() with an error	string.	 This is automagically
       caught and converted to an  exception of	'"undef"' type which can then
       be handled in the usual way.

	   die "I'm sorry Dave,	I can't	do that";

       Note that the '"undef"' we're talking about here	is a literal string
       rather than Perl's "undef" used to represent undefined values.

Template Runtime Options
   EVAL_PERL
       This flag is used to indicate if	"PERL" and/or "RAWPERL"	blocks should
       be evaluated.  It is disabled by	default	and any	"PERL" or "RAWPERL"
       blocks encountered will raise exceptions	of type	'"perl"' with the
       message '"EVAL_PERL not set"'.  Note however that any "RAWPERL" blocks
       should always contain valid Perl	code, regardless of the	"EVAL_PERL"
       flag.  The parser will fail to compile templates	that contain invalid
       Perl code in "RAWPERL" blocks and will throw a '"file"' exception.

       When using compiled templates (see "Caching and Compiling Options"),
       the "EVAL_PERL" has an affect when the template is compiled, and	again
       when the	templates is subsequently processed, possibly in a different
       context to the one that compiled	it.

       If the "EVAL_PERL" is set when a	template is compiled, then all "PERL"
       and "RAWPERL" blocks will be included in	the compiled template.	If the
       "EVAL_PERL" option isn't	set, then Perl code will be generated which
       always throws a '"perl"'	exception with the message '"EVAL_PERL not
       set"' whenever the compiled template code is run.

       Thus, you must have "EVAL_PERL" set if you want your compiled templates
       to include "PERL" and "RAWPERL" blocks.

       At some point in	the future, using a different invocation of the
       Template	Toolkit, you may come to process such a	pre-compiled template.
       Assuming	the "EVAL_PERL"	option was set at the time the template	was
       compiled, then the output of any	"RAWPERL" blocks will be included in
       the compiled template and will get executed when	the template is
       processed.  This	will happen regardless of the runtime "EVAL_PERL"
       status.

       Regular "PERL" blocks are a little more cautious, however.  If the
       "EVAL_PERL" flag	isn't set for the current context, that	is, the	one
       which is	trying to process it, then it will throw the familiar '"perl"'
       exception with the message, '"EVAL_PERL not set"'.

       Thus you	can compile templates to include "PERL"	blocks,	but optionally
       disable them when you process them later.  Note however that it is
       possible	for a "PERL" block to contain a	Perl ""BEGIN { # some code }""
       block which will	always get run regardless of the runtime "EVAL_PERL"
       status.	Thus, if you set "EVAL_PERL" when compiling templates, it is
       assumed that you	trust the templates to Do The Right Thing.  Otherwise
       you must	accept the fact	that there's no	bulletproof way	to prevent any
       included	code from trampling around in the living room of the runtime
       environment, making a real nuisance of itself if	it really wants	to.
       If you don't like the idea of such uninvited guests causing a bother,
       then you	can accept the default and keep	"EVAL_PERL" disabled.

   OUTPUT
       Default output location or handler.  This may be	specified as one of: a
       file name (relative to "OUTPUT_PATH", if	defined, or the	current
       working directory if not	specified absolutely); a file handle (e.g.
       "GLOB" or IO::Handle) opened for	writing; a reference to	a text string
       to which	the output is appended (the string isn't cleared); a reference
       to a subroutine which is	called,	passing	the output text	as an
       argument; as a reference	to an array, onto which	the content will be
       "push()"ed; or as a reference to	any object that	supports the "print()"
       method.	This latter option includes the	"Apache::Request" object which
       is passed as the	argument to Apache/mod_perl handlers.

       example 1 (file name):

	   my $template	= Template->new({
	       OUTPUT => "/tmp/foo",
	   });

       example 2 (text string):

	   my $output	= '';
	   my $template	= Template->new({
	       OUTPUT => \$output,
	   });

       example 3 (file handle):

	   open	(TOUT, ">", $file) || die "$file: $!\n";
	   my $template	= Template->new({
	       OUTPUT => \*TOUT,
	   });

       example 4 (subroutine):

	   sub output {	my $out	= shift; print "OUTPUT:	$out" }
	   my $template	= Template->new({
	       OUTPUT => \&output,
	   });

       example 5 (array	reference):

	   my $template	= Template->new({
	       OUTPUT => \@output,
	   })

       example 6 (Apache/mod_perl handler):

	   sub handler {
	       my $r = shift;
	       my $t = Template->new({
		   OUTPUT => $r,
	       });
	       ...
	   }

       The default "OUTPUT" location be	overridden by passing a	third
       parameter to the	Template process() method. This	can be specified as
       any of the above	argument types.

	   $t->process($file, $vars, "/tmp/foo");
	   $t->process($file, $vars, \$output);
	   $t->process($file, $vars, \*MYGLOB);
	   $t->process($file, $vars, \@output);
	   $t->process($file, $vars, $r);  # Apache::Request
	   ...

   OUTPUT_PATH
       The "OUTPUT_PATH" allows	a directory to be specified into which output
       files should be written.	 An output file	can be specified by the
       "OUTPUT"	option,	or passed by name as the third parameter to the
       Template	process() method.

	   my $template	= Template->new({
	       INCLUDE_PATH => "/tmp/src",
	       OUTPUT_PATH  => "/tmp/dest",
	   });

	   my $vars = {
	       ...
	   };

	   foreach my $file ('foo.html', 'bar.html') {
	       $template->process($file, $vars,	$file)
		   || die $template->error();
	   }

       This example will read the input	files /tmp/src/foo.html	and
       /tmp/src/bar.html and write the processed output	to /tmp/dest/foo.html
       and /tmp/dest/bar.html, respectively.

   STRICT
       By default the Template Toolkit will silently ignore the	use of
       undefined variables (a bad design decision that I regret).

       When the	"STRICT" option	is set,	the use	of any undefined variables or
       values will cause an exception to be throw.  The	exception will have a
       "type" of "var.undefined" and a message of the form "undefined
       variable: xxx".

	   my $template	= Template->new(
	       STRICT => 1
	   );

   DEBUG
       The "DEBUG" option can be used to enable	debugging within the various
       different modules that comprise the Template Toolkit.  The
       Template::Constants module defines a set	of "DEBUG_XXXX"	constants
       which can be combined using the logical OR operator, '"|"'.

	   use Template::Constants qw( :debug );

	   my $template	= Template->new({
	       DEBUG =>	DEBUG_PARSER | DEBUG_PROVIDER,
	   });

       For convenience,	you can	also provide a string containing a list	of
       lower case debug	options, separated by any non-word characters.

	   my $template	= Template->new({
	       DEBUG =>	'parser, provider',
	   });

       The following "DEBUG_XXXX" flags	can be used:

       DEBUG_SERVICE
	   Enables general debugging messages for the Template::Service
	   module.

       DEBUG_CONTEXT
	   Enables general debugging messages for the Template::Context
	   module.

       DEBUG_PROVIDER
	   Enables general debugging messages for the Template::Provider
	   module.

       DEBUG_PLUGINS
	   Enables general debugging messages for the Template::Plugins
	   module.

       DEBUG_FILTERS
	   Enables general debugging messages for the Template::Filters
	   module.

       DEBUG_PARSER
	   This	flag causes the	Template::Parser to generate debugging
	   messages that show the Perl code generated by parsing and compiling
	   each	template.

       DEBUG_UNDEF
	   This	option causes the Template Toolkit to throw an '"undef"' error
	   whenever it encounters an undefined variable	value.

       DEBUG_DIRS
	   This	option causes the Template Toolkit to generate comments
	   indicating the source file, line and	original text of each
	   directive in	the template.  These comments are embedded in the
	   template output using the format defined in the "DEBUG_FORMAT"
	   configuration item, or a simple default format if unspecified.

	   For example,	the following template fragment:

	       Hello World

	   would generate this output:

	       ## input	text line 1 :  ##
	       Hello
	       ## input	text line 2 : World ##
	       World

       DEBUG_ALL
	   Enables all debugging messages.

       DEBUG_CALLER
	   This	option causes all debug	messages that aren't newline
	   terminated to have the file name and	line number of the caller
	   appended to them.

   DEBUG_FORMAT
       The "DEBUG_FORMAT" option can be	used to	specify	a format string	for
       the debugging messages generated	via the	"DEBUG_DIRS" option described
       above.  Any occurrences of $file, $line or $text	will be	replaced with
       the current file	name, line or directive	text, respectively.  Notice
       how the format is single	quoted to prevent Perl from interpolating
       those tokens as variables.

	   my $template	= Template->new({
	       DEBUG =>	'dirs',
	       DEBUG_FORMAT => '<!-- $file line	$line :	[% $text %] -->',
	   });

       The following template fragment:

	   [% foo = 'World' %]
	   Hello [% foo	%]

       would then generate this	output:

	   <!--	input text line	2 : [% foo = 'World' %]	-->
	   Hello <!-- input text line 3	: [% foo %] -->World

       The DEBUG directive can also be used to set a debug format within a
       template.

	   [% DEBUG format '<!-- $file line $line : [% $text %]	-->' %]

Caching	and Compiling Options
   CACHE_SIZE
       The Template::Provider module caches compiled templates to avoid	the
       need to re-parse	template files or blocks each time they	are used. The
       "CACHE_SIZE" option is used to limit the	number of compiled templates
       that the	module should cache.

       By default, the "CACHE_SIZE" is undefined and all compiled templates
       are cached.  When set to	any positive value, the	cache will be limited
       to storing no more than that number of compiled templates.  When	a new
       template	is loaded and compiled and the cache is	full (i.e. the number
       of entries == "CACHE_SIZE"), the	least recently used compiled template
       is discarded to make room for the new one.

       The "CACHE_SIZE"	can be set to 0	to disable caching altogether.

	   my $template	= Template->new({
	       CACHE_SIZE => 64,   # only cache	64 compiled templates
	   });

	   my $template	= Template->new({
	       CACHE_SIZE => 0,	  # don't cache	any compiled templates
	   });

       As well as caching templates as they are	found, the Template::Provider
       also implements negative	caching	to keep	track of templates that	are
       not found.  This	allows the provider to quickly decline a request for a
       template	that it	has previously failed to locate, saving	the effort of
       going to	look for it again.  This is useful when	an "INCLUDE_PATH"
       includes	multiple providers, ensuring that the request is passed	down
       through the providers as	quickly	as possible.

   STAT_TTL
       This value can be set to	control	how long the Template::Provider	will
       keep a template cached in memory	before checking	to see if the source
       template	has changed.

	   my $provider	= Template::Provider->new({
	       STAT_TTL	=> 60,	# one minute
	   });

       The default value is 1 (second).	You'll probably	want to	set this to a
       higher value if you're running the Template Toolkit inside a persistent
       web server application (e.g. mod_perl). For example, set	it to 60 and
       the provider will only look for changes to templates once a minute at
       most. However, during development (or any time you're making frequent
       changes to templates) you'll probably want to keep it set to a low
       value so	that you don't have to wait for	the provider to	notice that
       your templates have changed.

   COMPILE_EXT
       From version 2 onwards, the Template Toolkit has	the ability to compile
       templates to Perl code and save them to disk for	subsequent use (i.e.
       cache persistence).  The	"COMPILE_EXT" option may be provided to
       specify a filename extension for	compiled template files.  It is
       undefined by default and	no attempt will	be made	to read	or write any
       compiled	template files.

	   my $template	= Template->new({
	       COMPILE_EXT => '.ttc',
	   });

       If "COMPILE_EXT"	is defined (and	"COMPILE_DIR" isn't, see below)	then
       compiled	template files with the	"COMPILE_EXT" extension	will be
       written to the same directory from which	the source template files were
       loaded.

       Compiling and subsequent	reuse of templates happens automatically
       whenever	the "COMPILE_EXT" or "COMPILE_DIR" options are set.  The
       Template	Toolkit	will automatically reload and reuse compiled files
       when it finds them on disk.  If the corresponding source	file has been
       modified	since the compiled version as written, then it will load and
       re-compile the source and write a new compiled version to disk.

       This form of cache persistence offers significant benefits in terms of
       time and	resources required to reload templates.	 Compiled templates
       can be reloaded by a simple call	to Perl's "require()", leaving Perl to
       handle all the parsing and compilation.	This is	a Good Thing.

   COMPILE_DIR
       The "COMPILE_DIR" option	is used	to specify an alternate	directory root
       under which compiled template files should be saved.

	   my $template	= Template->new({
	       COMPILE_DIR => '/tmp/ttc',
	   });

       The "COMPILE_EXT" option	may also be specified to have a	consistent
       file extension added to these files.

	   my $template1 = Template->new({
	       COMPILE_DIR => '/tmp/ttc',
	       COMPILE_EXT => '.ttc1',
	   });

	   my $template2 = Template->new({
	       COMPILE_DIR => '/tmp/ttc',
	       COMPILE_EXT => '.ttc2',
	   });

       When "COMPILE_EXT" is undefined,	the compiled template files have the
       same name as the	original template files, but reside in a different
       directory tree.

       Each directory in the "INCLUDE_PATH" is replicated in full beneath the
       "COMPILE_DIR" directory.	 This example:

	   my $template	= Template->new({
	       COMPILE_DIR  => '/tmp/ttc',
	       INCLUDE_PATH => '/home/abw/templates:/usr/share/templates',
	   });

       would create the	following directory structure:

	   /tmp/ttc/home/abw/templates/
	   /tmp/ttc/usr/share/templates/

       Files loaded from different "INCLUDE_PATH" directories will have	their
       compiled	forms save in the relevant "COMPILE_DIR" directory.

       On Win32	platforms a filename may by prefixed by	a drive	letter and
       colon.  e.g.

	   C:/My Templates/header

       The colon will be silently stripped from	the filename when it is	added
       to the "COMPILE_DIR" value(s) to	prevent	illegal	filename being
       generated.  Any colon in	"COMPILE_DIR" elements will be left intact.
       For example:

	   # Win32 only
	   my $template	= Template->new({
	       DELIMITER    => ';',
	       COMPILE_DIR  => 'C:/TT2/Cache',
	       INCLUDE_PATH => 'C:/TT2/Templates;D:/My Templates',
	   });

       This would create the following cache directories:

	   C:/TT2/Cache/C/TT2/Templates
	   C:/TT2/Cache/D/My Templates

Plugins	and Filters
   PLUGINS
       The "PLUGINS" options can be used to provide a reference	to a hash
       array that maps plugin names to Perl module names.  A number of
       standard	plugins	are defined (e.g. "table", "format", "cgi", etc.)
       which map to their corresponding	"Template::Plugin::*" counterparts.
       These can be redefined by values	in the "PLUGINS" hash.

	   my $template	= Template->new({
	       PLUGINS => {
		   cgi => 'MyOrg::Template::Plugin::CGI',
		   foo => 'MyOrg::Template::Plugin::Foo',
		   bar => 'MyOrg::Template::Plugin::Bar',
	       },
	   });

       The recommended convention is to	specify	these plugin names in lower
       case.  The Template Toolkit first looks for an exact case-sensitive
       match and then tries the	lower case conversion of the name specified.

	   [% USE Foo %]      #	look for 'Foo' then 'foo'

       If you define all your "PLUGINS"	with lower case	names then they	will
       be located regardless of	how the	user specifies the name	in the USE
       directive.  If, on the other hand, you define your "PLUGINS" with upper
       or mixed	case names then	the name specified in the "USE"	directive must
       match the case exactly.

       The "USE" directive is used to create plugin objects and	does so	by
       calling the plugin() method on the current Template::Context object. If
       the plugin name is defined in the "PLUGINS" hash	then the corresponding
       Perl module is loaded via "require()". The context then calls the
       load() class method which should	return the class name (default and
       general case) or	a prototype object against which the new() method can
       be called to instantiate	individual plugin objects.

       If the plugin name is not defined in the	"PLUGINS" hash then the
       "PLUGIN_BASE" and/or "LOAD_PERL"	options	come into effect.

   PLUGIN_BASE
       If a plugin is not defined in the "PLUGINS" hash	then the "PLUGIN_BASE"
       is used to attempt to construct a correct Perl module name which	can be
       successfully loaded.

       The "PLUGIN_BASE" can be	specified as a reference to an array of	module
       namespaces, or as a single value	which is automatically converted to a
       list.  The default "PLUGIN_BASE"	value ("Template::Plugin") is then
       added to	the end	of this	list.

       example 1:

	   my $template	= Template->new({
	       PLUGIN_BASE => 'MyOrg::Template::Plugin',
	   });

	   [% USE Foo %]    # => MyOrg::Template::Plugin::Foo
			      or	Template::Plugin::Foo

       example 2:

	   my $template	= Template->new({
	       PLUGIN_BASE => [	  'MyOrg::Template::Plugin',
				  'YourOrg::Template::Plugin'  ],
	   });

       template:

	   [% USE Foo %]    # =>   MyOrg::Template::Plugin::Foo
			      or YourOrg::Template::Plugin::Foo
			      or	  Template::Plugin::Foo

       If you don't want the default "Template::Plugin"	namespace added	to the
       end of the "PLUGIN_BASE", then set the $Template::Plugins::PLUGIN_BASE
       variable	to a false value before	calling	the new() Template#new()
       constructor method.  This is shown in the example below where the "Foo"
       plugin is located as "My::Plugin::Foo" or "Your::Plugin::Foo" but not
       as "Template::Plugin::Foo".

       example 3:

	   use Template::Plugins;
	   $Template::Plugins::PLUGIN_BASE = '';

	   my $template	= Template->new({
	       PLUGIN_BASE => [	  'My::Plugin',
				  'Your::Plugin'  ],
	   });

       template:

	   [% USE Foo %]    # =>   My::Plugin::Foo
			      or Your::Plugin::Foo

   LOAD_PERL
       If a plugin cannot be loaded using the "PLUGINS"	or "PLUGIN_BASE"
       approaches then the provider can	make a final attempt to	load the
       module without prepending any prefix to the module path.	 This allows
       regular Perl modules (i.e. those	that don't reside in the
       Template::Plugin	or some	other such namespace) to be loaded and used as
       plugins.

       By default, the "LOAD_PERL" option is set to 0 and no attempt will be
       made to load any	Perl modules that aren't named explicitly in the
       "PLUGINS" hash or reside	in a package as	named by one of	the
       "PLUGIN_BASE" components.

       Plugins loaded using the	"PLUGINS" or "PLUGIN_BASE" receive a reference
       to the current context object as	the first argument to the new()
       constructor. Modules loaded using "LOAD_PERL" are assumed to not
       conform to the plugin interface.	They must provide a "new()" class
       method for instantiating	objects	but it will not	receive	a reference to
       the context as the first	argument.

       Plugin modules should provide a load() class method (or inherit the
       default one from	the Template::Plugin base class) which is called the
       first time the plugin is	loaded.	Regular	Perl modules need not. In all
       other respects, regular Perl objects and	Template Toolkit plugins are
       identical.

       If a particular Perl module does	not conform to the common, but not
       unilateral, "new()" constructor convention then a simple	plugin wrapper
       can be written to interface to it.

   FILTERS
       The "FILTERS" option can	be used	to specify custom filters which	can
       then be used with the "FILTER" directive	like any other.	 These are
       added to	the standard filters which are available by default.  Filters
       specified via this option will mask any standard	filters	of the same
       name.

       The "FILTERS" option should be specified	as a reference to a hash array
       in which	each key represents the	name of	a filter.  The corresponding
       value should contain a reference	to an array containing a subroutine
       reference and a flag which indicates if the filter is static (0)	or
       dynamic (1).  A filter may also be specified as a solitary subroutine
       reference and is	assumed	to be static.

	   $template = Template->new({
	       FILTERS => {
		   'sfilt1' =>	 \&static_filter,      # static
		   'sfilt2' => [ \&static_filter, 0 ], # same as above
		   'dfilt1' => [ \&dyanamic_filter_factory, 1 ],
	       },
	   });

       Additional filters can be specified at any time by calling the
       define_filter() method on the current Template::Context object. The
       method accepts a	filter name, a reference to a filter subroutine	and an
       optional	flag to	indicate if the	filter is dynamic.

	   my $context = $template->context();
	   $context->define_filter('new_html', \&new_html);
	   $context->define_filter('new_repeat', \&new_repeat, 1);

       Static filters are those	where a	single subroutine reference is used
       for all invocations of a	particular filter.  Filters that don't accept
       any configuration parameters (e.g. "html") can be implemented
       statically.  The	subroutine reference is	simply returned	when that
       particular filter is requested.	The subroutine is called to filter the
       output of a template block which	is passed as the only argument.	 The
       subroutine should return	the modified text.

	   sub static_filter {
	       my $text	= shift;
	       # do something to modify	$text...
	       return $text;
	   }

       The following template fragment:

	   [% FILTER sfilt1 %]
	   Blah	blah blah.
	   [% END %]

       is approximately	equivalent to:

	   &static_filter("\nBlah blah blah.\n");

       Filters that can	accept parameters (e.g.	"truncate") should be
       implemented dynamically.	 In this case, the subroutine is taken to be a
       filter 'factory'	that is	called to create a unique filter subroutine
       each time one is	requested.  A reference	to the current
       Template::Context object	is passed as the first parameter, followed by
       any additional parameters specified.  The subroutine should return
       another subroutine reference (usually a closure)	which implements the
       filter.

	   sub dynamic_filter_factory {
	       my ($context, @args) = @_;

	       return sub {
		   my $text = shift;
		   # do	something to modify $text...
		   return $text;
	       }
	   }

       The following template fragment:

	   [% FILTER dfilt1(123, 456) %]
	   Blah	blah blah
	   [% END %]

       is approximately	equivalent to:

	   my $filter =	&dynamic_filter_factory($context, 123, 456);
	   &$filter("\nBlah blah blah.\n");

       See the "FILTER"	directive for further examples.

Customisation and Extension
   LOAD_TEMPLATES
       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 $template	= Template->new({
	       LOAD_TEMPLATES => [
		   MyOrg::Template::Provider->new({ ...	}),
		   Template::Provider->new({ ... }),
	       ],
	   });

       When a "PROCESS", "INCLUDE" or "WRAPPER"	directive is encountered, the
       named template may refer	to a locally defined "BLOCK" or	a file
       relative	to the "INCLUDE_PATH" (or an absolute or relative path if the
       appropriate "ABSOLUTE" or "RELATIVE" options are	set). If a "BLOCK"
       definition can't	be found (see the Template::Context template() method
       for a discussion	of "BLOCK" locality) then each of the "LOAD_TEMPLATES"
       provider	objects	is queried in turn via the fetch() method to see if it
       can supply the required template.

       Each provider can return	a compiled template, an	error, or decline to
       service the request in which case the responsibility is passed to the
       next provider.  If none of the providers	can service the	request	then a
       'not found' error is returned. The same basic provider mechanism	is
       also used for the "INSERT" directive but	it bypasses any	"BLOCK"
       definitions and doesn't attempt is to parse or process the contents of
       the template file.

       If "LOAD_TEMPLATES" is undefined, a single default provider will	be
       instantiated using the current configuration parameters.	For example,
       the Template::Provider "INCLUDE_PATH" option can	be specified in	the
       Template	configuration and will be correctly passed to the provider's
       constructor method.

	   my $template	= Template->new({
	       INCLUDE_PATH => '/here:/there',
	   });

   LOAD_PLUGINS
       The "LOAD_PLUGINS" options can be used to specify a list	of provider
       objects (i.e. they implement the	fetch()	method)	which are responsible
       for loading and instantiating template plugin objects. The
       Template::Context plugin() method queries each provider in turn in a
       "Chain of Responsibility" as per	the template() and filter() methods.

	   my $template	= Template->new({
	       LOAD_PLUGINS => [
		   MyOrg::Template::Plugins->new({ ... }),
		   Template::Plugins->new({ ...	}),
	       ],
	   });

       By default, a single Template::Plugins object is	created	using the
       current configuration hash.  Configuration items	destined for the
       Template::Plugins constructor may be added to the Template constructor.

	   my $template	= Template->new({
	       PLUGIN_BASE => 'MyOrg::Template::Plugins',
	       LOAD_PERL   => 1,
	   });

   LOAD_FILTERS
       The "LOAD_FILTERS" option can be	used to	specify	a list of provider
       objects (i.e. they implement the	fetch()	method)	which are responsible
       for returning and/or creating filter subroutines. The Template::Context
       filter()	method queries each provider in	turn in	a "Chain of
       Responsibility" as per the template() and plugin() methods.

	   my $template	= Template->new({
	       LOAD_FILTERS => [
		   MyTemplate::Filters->new(),
		   Template::Filters->new(),
	       ],
	   });

       By default, a single Template::Filters object is	created	for the
       "LOAD_FILTERS" list.

   TOLERANT
       The "TOLERANT" flag is used by the various Template Toolkit provider
       modules (Template::Provider, Template::Plugins, Template::Filters) to
       control their behaviour when errors are encountered. By default,	any
       errors are reported as such, with the request for the particular
       resource	("template", "plugin", "filter") being denied and an exception
       raised.

       When the	"TOLERANT" flag	is set to any true values, errors will be
       silently	ignored	and the	provider will instead return
       "STATUS_DECLINED". This allows a	subsequent provider to take
       responsibility for providing the	resource, rather than failing the
       request outright. If all	providers decline to service the request,
       either through tolerated	failure	or a genuine disinclination to comply,
       then a '"<resource> not found"' exception is raised.

   SERVICE
       A reference to a	Template::Service object, or sub-class thereof,	to
       which the Template module should	delegate.  If unspecified, a
       Template::Service object	is automatically created using the current
       configuration hash.

	   my $template	= Template->new({
	       SERVICE => MyOrg::Template::Service->new({ ... }),
	   });

   CONTEXT
       A reference to a	Template::Context object which is used to define a
       specific	environment in which template are processed. A
       Template::Context object	is passed as the only parameter	to the Perl
       subroutines that	represent "compiled" template documents. Template
       subroutines make	callbacks into the context object to access Template
       Toolkit functionality, for example, to "INCLUDE"	or "PROCESS" another
       template	(include() and process() methods, respectively), to "USE" a
       plugin (plugin()) or instantiate	a filter (filter()) or to access the
       stash (stash()) which manages variable definitions via the get()	and
       set() methods.

	   my $template	= Template->new({
	       CONTEXT => MyOrg::Template::Context->new({ ... }),
	   });

   STASH
       A reference to a	Template::Stash	object or sub-class which will take
       responsibility for managing template variables.

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

       If unspecified, a default stash object is created using the "VARIABLES"
       configuration item to initialise	the stash variables.

	   my $template	= Template->new({
	       VARIABLES => {
		   id	 => 'abw',
		   name	 => 'Andy Wardley',
	       },
	   };

   PARSER
       The Template::Parser module implements a	parser object for compiling
       templates into Perl code	which can then be executed.  A default object
       of this class is	created	automatically and then used by the
       Template::Provider whenever a template is loaded	and requires
       compilation.  The "PARSER" option can be	used to	provide	a reference to
       an alternate parser object.

	   my $template	= Template->new({
	       PARSER => MyOrg::Template::Parser->new({	... }),
	   });

   GRAMMAR
       The "GRAMMAR" configuration item	can be used to specify an alternate
       grammar for the parser.	This allows a modified or entirely new
       template	language to be constructed and used by the Template Toolkit.

       Source templates	are compiled to	Perl code by the Template::Parser
       using the Template::Grammar (by default)	to define the language
       structure and semantics.	 Compiled templates are	thus inherently
       "compatible" with each other and	there is nothing to prevent any	number
       of different template languages being compiled and used within the same
       Template	Toolkit	processing environment (other than the usual time and
       memory constraints).

       The Template::Grammar file is constructed from a	YACC like grammar
       (using "Parse::YAPP") and a skeleton module template.  These files are
       provided, along with a small script to rebuild the grammar, in the
       parser sub-directory of the distribution.

       You don't have to know or worry about these unless you want to hack on
       the template language or	define your own	variant. There is a README
       file in the same	directory which	provides some small guidance but it is
       assumed that you	know what you're doing if you venture herein. If you
       grok LALR parsers, then you should find it comfortably familiar.

       By default, an instance of the default Template::Grammar	will be
       created and used	automatically if a "GRAMMAR" item isn't	specified.

	   use MyOrg::Template::Grammar;

	   my $template	= Template->new({
	       GRAMMAR = MyOrg::Template::Grammar->new();
	   });

perl v5.32.0			  2020-03-30	   Template::Manual::Config(3)

NAME | Template Style and Parsing Options | Template Files and Blocks | Template Variables | Template Processing Options | Template Runtime Options | Caching and Compiling Options | Plugins and Filters | Customisation and Extension

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Template::Manual::Config&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help