{
    "mode": "perldoc",
    "parameter": "Template::Manual::Config",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Template%3A%3AManual%3A%3AConfig/json",
    "generated": "2026-11-09T23:32:30Z",
    "sections": {
        "NAME": {
            "content": "Template::Manual::Config - Configuration options\n",
            "subsections": []
        },
        "Template Style and Parsing Options": {
            "content": "ENCODING\nThe \"ENCODING\" option specifies the template files' character encoding:\n\nmy $template = Template->new({\nENCODING => 'utf8',\n});\n\nA template which starts with a Unicode byte order mark (BOM) will have its encoding detected\nautomatically.\n\nSTARTTAG, ENDTAG\nThe \"STARTTAG\" and \"ENDTAG\" options are used to specify character sequences or regular\nexpressions that mark the start and end of inline template directives. The default values for\n\"STARTTAG\" and \"ENDTAG\" are '\"[%\"' and '\"%]\"' respectively, giving us the familiar directive\nstyle:\n\n[% example %]\n\nAny Perl regex characters can be used and therefore should be escaped (or use the Perl\n\"quotemeta\" function) if they are intended to represent literal characters.\n\nmy $template = Template->new({\nSTARTTAG => quotemeta('<+'),\nENDTAG   => quotemeta('+>'),\n});\n\nExample:\n\n<+ INCLUDE foobar +>\n\nThe \"TAGS\" directive can also be used to set the \"STARTTAG\" and \"ENDTAG\" values on a\nper-template file basis.\n\n[% TAGS <+ +> %]\n\nOUTLINETAG\nThe \"OUTLINETAG\" option can be used to enable single-line \"outline\" directives.\n\nmy $template = Template->new({\nOUTLINETAG => '%%',\n});\n\nThis allows you to use both inline and outline tags like so:\n\n%% IF user\nHello [% user.name %]\n%% END\n\nThe \"OUTLINETAG\" string (or regex) must appear at the start of a line. The directive continues\nuntil the end of the line. The newline character at the end of the line is considered to be the\ninvisible end-of-directive marker and is removed.\n\nTAGSTYLE\nThe \"TAGSTYLE\" option can be used to set both \"STARTTAG\" and \"ENDTAG\" according to\npre-defined tag styles.\n\nmy $template = Template->new({\nTAGSTYLE => 'star',\n});\n\nAvailable styles are:\n\ntemplate    [% ... %]               (default)\ntemplate1   [% ... %] or %% ... %%  (TT version 1)\nmetatext    %% ... %%               (Text::MetaText)\nstar        [* ... *]               (TT alternate)\nphp         <? ... ?>               (PHP)\nasp         <% ... %>               (ASP)\nmason       <% ...  >               (HTML::Mason)\nhtml        <!-- ... -->            (HTML comments)\n\nThe \"outline\" style uses the default markers for \"STARTTAG\" and \"ENDTAG\" (\"[%\" and \"%]\"\nrespectively) and additionally defines \"OUTLINETAG\" to be \"%%\".\n\nmy $template = Template->new({\nTAGSTYLE => 'outline',\n});\n\nThis allows you to use both inline and outline tags like so:\n\n%% IF user\nHello [% user.name %]\n%% END\n\nAny values specified for \"STARTTAG\", \"ENDTAG\" and/or \"OUTLINETAG\" will override those defined\nby a \"TAGSTYLE\".\n\nThe \"TAGS\" directive may also be used to set a \"TAGSTYLE\"\n\n[% TAGS html %]\n<!-- INCLUDE header -->\n\nPRECHOMP, POSTCHOMP\nAnything outside a directive tag is considered plain text and is generally passed through\nunaltered (but see the INTERPOLATE option). This includes all whitespace and newlines characters\nsurrounding directive tags. Directives that don't generate any output will leave gaps in the\noutput document.\n\nExample:\n\nFoo\n[% a = 10 %]\nBar\n\nOutput:\n\nFoo\n\nBar\n\nThe \"PRECHOMP\" and \"POSTCHOMP\" options can help to clean up some of this extraneous\nwhitespace. Both are disabled by default.\n\nmy $template = Template-E<gt>new({\nPRECHOMP  => 1,\nPOSTCHOMP => 1,\n});\n\nWith \"PRECHOMP\" set to 1, the newline and whitespace preceding a directive at the start of a\nline will be deleted. This has the effect of concatenating a line that starts with a directive\nonto the end of the previous line.\n\nFoo <----------.\n|\n,---(PRECHOMP)----'\n|\n`-- [% a = 10 %] --.\n|\n,---(POSTCHOMP)---'\n|\n`-> Bar\n\nWith \"POSTCHOMP\" set to 1, any whitespace after a directive up to and including the newline\nwill be deleted. This has the effect of joining a line that ends with a directive onto the start\nof the next line.\n\nIf \"PRECHOMP\" or \"POSTCHOMP\" is set to 2, all whitespace including any number of newline will\nbe removed and replaced with a single space. This is useful for HTML, where (usually) a\ncontiguous block of whitespace is rendered the same as a single space.\n\nWith \"PRECHOMP\" or \"POSTCHOMP\" set to 3, all adjacent whitespace (including newlines) will be\nremoved entirely.\n\nThese values are defined as \"CHOMPNONE\", \"CHOMPONE\", \"CHOMPCOLLAPSE\" and \"CHOMPGREEDY\"\nconstants in the Template::Constants module. \"CHOMPALL\" is also defined as an alias for\n\"CHOMPONE\" to provide backwards compatibility with earlier version of the Template Toolkit.\n\nAdditionally the chomp tag modifiers listed below may also be used for the \"PRECHOMP\" and\n\"POSTCHOMP\" configuration.\n\nmy $template = Template->new({\nPRECHOMP  => '~',\nPOSTCHOMP => '-',\n});\n\n\"PRECHOMP\" and \"POSTCHOMP\" can be activated for individual directives by placing a '\"-\"'\nimmediately at the start and/or end of the directive.\n\n[% FOREACH user IN userlist %]\n[%- user -%]\n[% END %]\n\nThis has the same effect as \"CHOMPONE\" in removing all whitespace before or after the directive\nup to and including the newline. The template will be processed as if written:\n\n[% FOREACH user IN userlist %][% user %][% END %]\n\nTo remove all whitespace including any number of newlines, use the '\"~\"' character instead.\n\n[% FOREACH user IN userlist %]\n\n[%~ user ~%]\n\n[% END %]\n\nTo collapse all whitespace to a single space, use the '\"=\"' character.\n\n[% FOREACH user IN userlist %]\n\n[%= user =%]\n\n[% END %]\n\nHere the template is processed as if written:\n\n[% FOREACH user IN userlist %] [% user %] [% END %]\n\nIf you have \"PRECHOMP\" or \"POSTCHOMP\" set as configuration options then you can use '\"+\"' to\ndisable any chomping options (i.e. leave the whitespace intact) on a per-directive basis.\n\n[% FOREACH user IN userlist %]\nUser: [% user +%]\n[% END %]\n\nWith \"POSTCHOMP\" set to \"CHOMPONE\", the above example would be parsed as if written:\n\n[% FOREACH user IN userlist %]User: [% user %]\n[% END %]\n\nFor reference, the \"PRECHOMP\" and \"POSTCHOMP\" configuration options may be set to any of the\nfollowing:\n\nConstant      Value   Tag Modifier\n----------------------------------\nCHOMPNONE      0          +\nCHOMPONE       1          -\nCHOMPCOLLAPSE  2          =\nCHOMPGREEDY    3          ~\n\nTRIM\nThe \"TRIM\" option can be set to have any leading and trailing whitespace automatically removed\nfrom the output of all template files and \"BLOCK\"s.\n\nBy example, the following \"BLOCK\" definition\n\n[% BLOCK foo %]\nLine 1 of foo\n[% END %]\n\nwill be processed is as \"\"\\nLine 1 of foo\\n\"\". When \"INCLUDE\"d, the surrounding newlines will\nalso be introduced.\n\nbefore\n[% INCLUDE foo %]\nafter\n\nGenerated output:\n\nbefore\n\nLine 1 of foo\n\nafter\n\nWith the \"TRIM\" option set to any true value, the leading and trailing newlines (which count as\nwhitespace) will be removed from the output of the \"BLOCK\".\n\nbefore\nLine 1 of foo\nafter\n\nThe \"TRIM\" option is disabled (0) by default.\n\nINTERPOLATE\nThe \"INTERPOLATE\" flag, when set to any true value will cause variable references in plain text\n(i.e. not surrounded by \"STARTTAG\" and \"ENDTAG\") to be recognised and interpolated\naccordingly.\n\nmy $template = Template->new({\nINTERPOLATE => 1,\n});\n\nVariables should be prefixed by a '\"$\"' to identify them. Curly braces can be used in the\nfamiliar Perl/shell style to explicitly scope the variable name where required.\n\n# INTERPOLATE => 0\n<a href=\"http://[% server %]/[% help %]\">\n<img src=\"[% images %]/help.gif\"></a>\n[% myorg.name %]\n\n# INTERPOLATE => 1\n<a href=\"http://$server/$help\">\n<img src=\"$images/help.gif\"></a>\n$myorg.name\n\n# explicit scoping with {  }\n<img src=\"$images/${icon.next}.gif\">\n\nNote that a limitation in Perl's regex engine restricts the maximum length of an interpolated\ntemplate to around 32 kilobytes or possibly less. Files that exceed this limit in size will\ntypically cause Perl to dump core with a segmentation fault. If you routinely process templates\nof this size then you should disable \"INTERPOLATE\" or split the templates in several smaller\nfiles or blocks which can then be joined backed together via \"PROCESS\" or \"INCLUDE\".\n\nANYCASE\nBy default, directive keywords should be expressed in UPPER CASE. The \"ANYCASE\" option can be\nset to allow directive keywords to be specified in any case.\n\n# ANYCASE => 0 (default)\n[% INCLUDE foobar %]        # OK\n[% include foobar %]        # ERROR\n[% include = 10   %]        # OK, 'include' is a variable\n\n# ANYCASE => 1\n[% INCLUDE foobar %]        # OK\n[% include foobar %]        # OK\n[% include = 10   %]        # ERROR, 'include' is reserved word\n\nOne side-effect of enabling \"ANYCASE\" is that you cannot use a variable of the same name as a\nreserved word, regardless of case. The reserved words are currently:\n\nGET CALL SET DEFAULT INSERT INCLUDE PROCESS WRAPPER\nIF UNLESS ELSE ELSIF FOR FOREACH WHILE SWITCH CASE\nUSE PLUGIN FILTER MACRO PERL RAWPERL BLOCK META\nTRY THROW CATCH FINAL NEXT LAST BREAK RETURN STOP\nCLEAR TO STEP AND OR NOT MOD DIV END\n\nThe only lower case reserved words that cannot be used for variables, regardless of the\n\"ANYCASE\" option, are the operators:\n\nand or not mod div\n",
            "subsections": []
        },
        "Template Files and Blocks": {
            "content": "INCLUDEPATH\nThe \"INCLUDEPATH\" is used to specify one or more directories in which template files are\nlocated. When a template is requested that isn't defined locally as a \"BLOCK\", each of the\n\"INCLUDEPATH\" directories is searched in turn to locate the template file. Multiple directories\ncan be specified as a reference to a list or as a single string where each directory is\ndelimited by '\":\"'.\n\nmy $template = Template->new({\nINCLUDEPATH => '/usr/local/templates',\n});\n\nmy $template = Template->new({\nINCLUDEPATH => '/usr/local/templates:/tmp/my/templates',\n});\n\nmy $template = Template->new({\nINCLUDEPATH => [ '/usr/local/templates',\n'/tmp/my/templates' ],\n});\n\nOn Win32 systems, a little extra magic is invoked, ignoring delimiters that have '\":\"' followed\nby a '\"/\"' or '\"\\\"'. This avoids confusion when using directory names like '\"C:\\Blah Blah\"'.\n\nWhen specified as a list, the \"INCLUDEPATH\" path can contain elements which dynamically\ngenerate a list of \"INCLUDEPATH\" directories. These generator elements can be specified as a\nreference to a subroutine or an object which implements a paths() method.\n\nmy $template = Template->new({\nINCLUDEPATH => [ '/usr/local/templates',\n\\&incpathgenerator,\nMy::IncPath::Generator->new( ... ) ],\n});\n\nEach time a template is requested and the \"INCLUDEPATH\" examined, the subroutine or object\nmethod will be called. A reference to a list of directories should be returned. Generator\nsubroutines should report errors using die(). Generator objects should return undef and make an\nerror available via its error() method.\n\nFor example:\n\nsub incpathgenerator {\n# ...some code...\n\nif ($alliswell) {\nreturn \\@listofdirectories;\n}\nelse {\ndie \"cannot generate INCLUDEPATH...\\n\";\n}\n}\n\nor:\n\npackage My::IncPath::Generator;\n\n# Template::Base (or Class::Base) provides error() method\nuse Template::Base;\nuse base qw( Template::Base );\n\nsub paths {\nmy $self = shift;\n\n# ...some code...\n\nif ($alliswell) {\nreturn \\@listofdirectories;\n}\nelse {\nreturn $self->error(\"cannot generate INCLUDEPATH...\\n\");\n}\n}\n\n1;\n\nDELIMITER\nUsed to provide an alternative delimiter character sequence for separating paths specified in\nthe \"INCLUDEPATH\". The default value for \"DELIMITER\" is '\":\"'.\n\nmy $template = Template->new({\nDELIMITER    => '; ',\nINCLUDEPATH => 'C:/HERE/NOW; D:/THERE/THEN',\n});\n\nOn Win32 systems, the default delimiter is a little more intelligent, splitting paths only on\n'\":\"' characters that aren't followed by a '\"/\"'. This means that the following should work as\nplanned, splitting the \"INCLUDEPATH\" into 2 separate directories, \"C:/foo\" and \"C:/bar\".\n\n# on Win32 only\nmy $template = Template->new({\nINCLUDEPATH => 'C:/Foo:C:/Bar'\n});\n\nHowever, if you're using Win32 then it's recommended that you explicitly set the \"DELIMITER\"\ncharacter to something else (e.g. '\";\"') rather than rely on this subtle magic.\n\nABSOLUTE\nThe \"ABSOLUTE\" flag is used to indicate if templates specified with absolute filenames (e.g.\n'\"/foo/bar\"') should be processed. It is disabled by default and any attempt to load a template\nby such a name will cause a '\"file\"' exception to be raised.\n\nmy $template = Template->new({\nABSOLUTE => 1,\n});\n\n# this is why it's disabled by default\n[% INSERT /etc/passwd %]\n\nOn Win32 systems, the regular expression for matching absolute pathnames is tweaked slightly to\nalso detect filenames that start with a driver letter and colon, such as:\n\nC:/Foo/Bar\n\nRELATIVE\nThe \"RELATIVE\" flag is used to indicate if templates specified with filenames relative to the\ncurrent directory (e.g. '\"./foo/bar\"' or '\"../../some/where/else\"') should be loaded. It is also\ndisabled by default, and will raise a '\"file\"' error if such template names are encountered.\n\nmy $template = Template->new({\nRELATIVE => 1,\n});\n\n[% INCLUDE ../logs/error.log %]\n\nDEFAULT\nThe \"DEFAULT\" option can be used to specify a default template which should be used whenever a\nspecified template can't be found in the \"INCLUDEPATH\".\n\nmy $template = Template->new({\nDEFAULT => 'notfound.html',\n});\n\nIf a non-existent template is requested through the Template process() method, or by an\n\"INCLUDE\", \"PROCESS\" or \"WRAPPER\" directive, then the \"DEFAULT\" template will instead be\nprocessed, if defined. Note that the \"DEFAULT\" template is not used when templates are specified\nwith absolute or relative filenames, or as a reference to a input file handle or text string.\n\nBLOCKS\nThe \"BLOCKS\" option can be used to pre-define a default set of template blocks. These should be\nspecified as a reference to a hash array mapping template names to template text, subroutines or\nTemplate::Document objects.\n\nmy $template = Template->new({\nBLOCKS => {\nheader  => 'The Header.  [% title %]',\nfooter  => sub { return $someoutputtext },\nanother => Template::Document->new({ ... }),\n},\n});\n\nVIEWS\nThe VIEWS option can be used to define one or more Template::View objects. They can be specified\nas a reference to a hash array or list reference.\n\nmy $template = Template->new({\nVIEWS => {\nmyview => { prefix => 'mytemplates/' },\n},\n});\n\nBe aware of the fact that Perl's hash array are unordered, so if you want to specify multiple\nviews of which one or more are based on other views, then you should use a list reference to\npreserve the order of definition.\n\nmy $template = Template->new({\nVIEWS => [\nbottom => { prefix => 'bottom/' },\nmiddle => { prefix => 'middle/', base => 'bottom' },\ntop    => { prefix => 'top/',    base => 'middle' },\n],\n});\n\nAUTORESET\nThe \"AUTORESET\" option is set by default and causes the local \"BLOCKS\" cache for the\nTemplate::Context object to be reset on each call to the Template process() method. This ensures\nthat any \"BLOCK\"s defined within a template will only persist until that template is finished\nprocessing. This prevents \"BLOCK\"s defined in one processing request from interfering with other\nindependent requests subsequently processed by the same context object.\n\nThe \"BLOCKS\" item may be used to specify a default set of block definitions for the\nTemplate::Context object. Subsequent \"BLOCK\" definitions in templates will over-ride these but\nthey will be reinstated on each reset if \"AUTORESET\" is enabled (default), or if the\nTemplate::Context reset() method is called.\n\nRECURSION\nThe template processor will raise a file exception if it detects direct or indirect recursion\ninto a template. Setting this option to any true value will allow templates to include each\nother recursively.\n",
            "subsections": []
        },
        "Template Variables": {
            "content": "VARIABLES\nThe \"VARIABLES\" option (or \"PREDEFINE\" - they're equivalent) can be used to specify a hash\narray of template variables that should be used to pre-initialise the stash when it is created.\nThese items are ignored if the \"STASH\" item is defined.\n\nmy $template = Template->new({\nVARIABLES => {\ntitle   => 'A Demo Page',\nauthor  => 'Joe Random Hacker',\nversion => 3.14,\n},\n};\n\nor\n\nmy $template = Template->new({\nPREDEFINE => {\ntitle   => 'A Demo Page',\nauthor  => 'Joe Random Hacker',\nversion => 3.14,\n},\n};\n\nCONSTANTS\nThe \"CONSTANTS\" option can be used to specify a hash array of template variables that are\ncompile-time constants. These variables are resolved once when the template is compiled, and\nthus don't require further resolution at runtime. This results in significantly faster\nprocessing of the compiled templates and can be used for variables that don't change from one\nrequest to the next.\n\nmy $template = Template->new({\nCONSTANTS => {\ntitle   => 'A Demo Page',\nauthor  => 'Joe Random Hacker',\nversion => 3.14,\n},\n};\n\nCONSTANTNAMESPACE\nConstant variables are accessed via the \"constants\" namespace by default.\n\n[% constants.title %]\n\nThe \"CONSTANTSNAMESPACE\" option can be set to specify an alternate namespace.\n\nmy $template = Template->new({\nCONSTANTS => {\ntitle   => 'A Demo Page',\n# ...etc...\n},\nCONSTANTSNAMESPACE => 'const',\n};\n\nIn this case the constants would then be accessed as:\n\n[% const.title %]\n\nNAMESPACE\nThe constant folding mechanism described above is an example of a namespace handler. Namespace\nhandlers can be defined to provide alternate parsing mechanisms for variables in different\nnamespaces.\n\nUnder the hood, the Template module converts a constructor configuration such as:\n\nmy $template = Template->new({\nCONSTANTS => {\ntitle   => 'A Demo Page',\n# ...etc...\n},\nCONSTANTSNAMESPACE => 'const',\n};\n\ninto one like:\n\nmy $template = Template->new({\nNAMESPACE => {\nconst => Template:::Namespace::Constants->new({\ntitle   => 'A Demo Page',\n# ...etc...\n}),\n},\n};\n\nYou can use this mechanism to define multiple constant namespaces, or to install custom handlers\nof your own.\n\nmy $template = Template->new({\nNAMESPACE => {\nsite => Template:::Namespace::Constants->new({\ntitle   => \"Wardley's Widgets\",\nversion => 2.718,\n}),\nauthor => Template:::Namespace::Constants->new({\nname  => 'Andy Wardley',\nemail => 'abw@andywardley.com',\n}),\nvoodoo => My::Namespace::Handler->new( ... ),\n},\n};\n\nNow you have two constant namespaces, for example:\n\n[% site.title %]\n[% author.name %]\n\nas well as your own custom namespace handler installed for the 'voodoo' namespace.\n\n[% voodoo.magic %]\n\nSee Template::Namespace::Constants for an example of what a namespace handler looks like on the\ninside.\n",
            "subsections": []
        },
        "Template Processing Options": {
            "content": "The following options are used to specify any additional templates that should be processed\nbefore, after, around or instead of the template passed as the first argument to the Template\nprocess() method. These options can be perform various useful tasks such as adding standard\nheaders or footers to all pages, wrapping page output in other templates, pre-defining variables\nor performing initialisation or cleanup tasks, automatically generating page summary\ninformation, navigation elements, and so on.\n\nThe task of processing the template is delegated internally to the Template::Service module\nwhich, unsurprisingly, also has a process() method. Any templates defined by the \"PREPROCESS\"\noption are processed first and any output generated is added to the output buffer. Then the main\ntemplate is processed, or if one or more \"PROCESS\" templates are defined then they are instead\nprocessed in turn. In this case, one of the \"PROCESS\" templates is responsible for processing\nthe main template, by a directive such as:\n\n[% PROCESS $template %]\n\nThe output of processing the main template or the \"PROCESS\" template(s) is then wrapped in any\n\"WRAPPER\" templates, if defined. \"WRAPPER\" templates don't need to worry about explicitly\nprocessing the template because it will have been done for them already. Instead \"WRAPPER\"\ntemplates access the content they are wrapping via the \"content\" variable.\n\nwrapper before\n[% content %]\nwrapper after\n\nThis output generated from processing the main template, and/or any \"PROCESS\" or \"WRAPPER\"\ntemplates is added to the output buffer. Finally, any \"POSTPROCESS\" templates are processed and\ntheir output is also added to the output buffer which is then returned.\n\nIf the main template throws an exception during processing then any relevant template(s) defined\nvia the \"ERROR\" option will be processed instead. If defined and successfully processed, the\noutput from the error template will be added to the output buffer in place of the template that\ngenerated the error and processing will continue, applying any \"WRAPPER\" and \"POSTPROCESS\"\ntemplates. If no relevant \"ERROR\" option is defined, or if the error occurs in one of the\n\"PREPROCESS\", \"WRAPPER\" or \"POSTPROCESS\" templates, then the process will terminate\nimmediately and the error will be returned.\n\nPREPROCESS, POSTPROCESS\nThese values may be set to contain the name(s) of template files (relative to \"INCLUDEPATH\")\nwhich should be processed immediately before and/or after each template. These do not get added\nto templates processed into a document via directives such as \"INCLUDE\", \"PROCESS\", \"WRAPPER\"\netc.\n\nmy $template = Template->new({\nPREPROCESS  => 'header',\nPOSTPROCESS => 'footer',\n};\n\nMultiple templates may be specified as a reference to a list. Each is processed in the order\ndefined.\n\nmy $template = Template->new({\nPREPROCESS  => [ 'config', 'header' ],\nPOSTPROCESS => 'footer',\n};\n\nAlternately, multiple template may be specified as a single string, delimited by '\":\"'. This\ndelimiter string can be changed via the \"DELIMITER\" option.\n\nmy $template = Template->new({\nPREPROCESS  => 'config:header',\nPOSTPROCESS => 'footer',\n};\n\nThe \"PREPROCESS\" and \"POSTPROCESS\" templates are evaluated in the same variable context as the\nmain document and may define or update variables for subsequent use.\n\nconfig:\n\n[% # set some site-wide variables\nbgcolor = '#ffffff'\nversion = 2.718\n%]\n\nheader:\n\n[% DEFAULT title = 'My Funky Web Site' %]\n<html>\n<head>\n<title>[% title %]</title>\n</head>\n<body bgcolor=\"[% bgcolor %]\">\n\nfooter:\n\n<hr>\nVersion [% version %]\n</body>\n</html>\n\nThe Template::Document object representing the main template being processed is available within\n\"PREPROCESS\" and \"POSTPROCESS\" templates as the \"template\" variable. Metadata items defined\nvia the \"META\" directive may be accessed accordingly.\n\n$template->process('mydoc.html', $vars);\n\nmydoc.html:\n\n[% META title = 'My Document Title' %]\nblah blah blah\n...\n\nheader:\n\n<html>\n<head>\n<title>[% template.title %]</title>\n</head>\n<body bgcolor=\"[% bgcolor %]\">\n\nPROCESS\nThe \"PROCESS\" option may be set to contain the name(s) of template files (relative to\n\"INCLUDEPATH\") which should be processed instead of the main template passed to the Template\nprocess() method. This can be used to apply consistent wrappers around all templates, similar to\nthe use of \"PREPROCESS\" and \"POSTPROCESS\" templates.\n\nmy $template = Template->new({\nPROCESS  => 'content',\n};\n\n# processes 'content' instead of 'foo.html'\n$template->process('foo.html');\n\nA reference to the original template is available in the \"template\" variable. Metadata items can\nbe inspected and the template can be processed by specifying it as a variable reference (i.e.\nprefixed by \"$\") to an \"INCLUDE\", \"PROCESS\" or \"WRAPPER\" directive.\n\ncontent:\n\n<html>\n<head>\n<title>[% template.title %]</title>\n</head>\n<body>\n<!-- begin content -->\n[% PROCESS $template %]\n<!-- end content -->\n<hr>\n&copy; Copyright [% template.copyright %]\n</body>\n</html>\n\nfoo.html:\n\n[% META\ntitle     = 'The Foo Page'\nauthor    = 'Fred Foo'\ncopyright = '2000 Fred Foo'\n%]\n<h1>[% template.title %]</h1>\nWelcome to the Foo Page, blah blah blah\n\noutput:\n\n<html>\n<head>\n<title>The Foo Page</title>\n</head>\n<body>\n<!-- begin content -->\n<h1>The Foo Page</h1>\nWelcome to the Foo Page, blah blah blah\n<!-- end content -->\n<hr>\n&copy; Copyright 2000 Fred Foo\n</body>\n</html>\n\nWRAPPER\nThe \"WRAPPER\" option can be used to specify one or more templates which should be used to wrap\naround the output of the main page template. The main template is processed first (or any\n\"PROCESS\" template(s)) and the output generated is then passed as the \"content\" variable to the\n\"WRAPPER\" template(s) as they are processed.\n\nmy $template = Template->new({\nWRAPPER => 'wrapper',\n};\n\n# process 'foo' then wrap in 'wrapper'\n$template->process('foo', { message => 'Hello World!' });\n\nwrapper:\n\n<wrapper>\n[% content %]\n</wrapper>\n\nfoo:\n\nThis is the foo file!\nMessage: [% message %]\n\nThe output generated from this example is:\n\n<wrapper>\nThis is the foo file!\nMessage: Hello World!\n</wrapper>\n\nYou can specify more than one \"WRAPPER\" template by setting the value to be a reference to a\nlist of templates. The \"WRAPPER\" templates will be processed in reverse order with the output of\neach being passed to the next (or previous, depending on how you look at it) as the 'content'\nvariable. It sounds complicated, but the end result is that it just \"Does The Right Thing\" to\nmake wrapper templates nest in the order you specify.\n\nmy $template = Template->new({\nWRAPPER => [ 'outer', 'inner' ],\n};\n\n# process 'foo' then wrap in 'inner', then in 'outer'\n$template->process('foo', { message => 'Hello World!' });\n\nouter:\n\n<outer>\n[% content %]\n</outer>\n\ninner:\n\n<inner>\n[% content %]\n</inner>\n\nThe output generated is then:\n\n<outer>\n<inner>\nThis is the foo file!\nMessage: Hello World!\n</inner>\n</outer>\n\nOne side-effect of the \"inside-out\" processing of the \"WRAPPER\" configuration item (and also the\n\"WRAPPER\" directive) is that any variables set in the template being wrapped will be visible to\nthe template doing the wrapping, but not the other way around.\n\nYou can use this to good effect in allowing page templates to set pre-defined values which are\nthen used in the wrapper templates. For example, our main page template 'foo' might look like\nthis:\n\nfoo:\n\n[% page = {\ntitle    = 'Foo Page'\nsubtitle = 'Everything There is to Know About Foo'\nauthor   = 'Frank Oliver Octagon'\n}\n%]\n\n<p>\nWelcome to the page that tells you everything about foo\nblah blah blah...\n</p>\n\nThe \"foo\" template is processed before the wrapper template meaning that the \"page\" data\nstructure will be defined for use in the wrapper template.\n\nwrapper:\n\n<html>\n<head>\n<title>[% page.title %]</title>\n</head>\n<body>\n<h1>[% page.title %]</h1>\n<h2>[% page.subtitle %]</h1>\n<h3>by [% page.author %]</h3>\n[% content %]\n</body>\n</html>\n\nIt achieves the same effect as defining \"META\" items which are then accessed via the \"template\"\nvariable (which you are still free to use within \"WRAPPER\" templates), but gives you more\nflexibility in the type and complexity of data that you can define.\n\nERROR\nThe \"ERROR\" (or \"ERRORS\" if you prefer) configuration item can be used to name a single template\nor specify a hash array mapping exception types to templates which should be used for error\nhandling. If an uncaught exception is raised from within a template then the appropriate error\ntemplate will instead be processed.\n\nIf specified as a single value then that template will be processed for all uncaught exceptions.\n\nmy $template = Template->new({\nERROR => 'error.html'\n});\n\nIf the \"ERROR\" item is a hash reference the keys are assumed to be exception types and the\nrelevant template for a given exception will be selected. A \"default\" template may be provided\nfor the general case. Note that \"ERROR\" can be pluralised to \"ERRORS\" if you find it more\nappropriate in this case.\n\nmy $template = Template->new({\nERRORS => {\nuser     => 'user/index.html',\ndbi      => 'error/database',\ndefault  => 'error/default',\n},\n});\n\nIn this example, any \"user\" exceptions thrown will cause the user/index.html template to be\nprocessed, \"dbi\" errors are handled by error/database and all others by the error/default\ntemplate. Any \"PREPROCESS\" and/or \"POSTPROCESS\" templates will also be applied to these error\ntemplates.\n\nNote that exception types are hierarchical and a \"foo\" handler will catch all \"foo.*\" errors\n(e.g. \"foo.bar\", \"foo.bar.baz\") if a more specific handler isn't defined. Be sure to quote any\nexception types that contain periods to prevent Perl concatenating them into a single string\n(i.e. \"user.passwd\" is parsed as 'user'.'passwd').\n\nmy $template = Template->new({\nERROR => {\n'user.login'  => 'user/login.html',\n'user.passwd' => 'user/badpasswd.html',\n'user'        => 'user/index.html',\n'default'     => 'error/default',\n},\n});\n\nIn this example, any template processed by the $template object, or other templates or code\ncalled from within, can raise a \"user.login\" exception and have the service redirect to the\nuser/login.html template. Similarly, a \"user.passwd\" exception has a specific handling template,\nuser/badpasswd.html, while all other \"user\" or \"user.*\" exceptions cause a redirection to the\nuser/index.html page. All other exception types are handled by error/default.\n\nExceptions can be raised in a template using the \"THROW\" directive,\n\n[% THROW user.login 'no user id: please login' %]\n\nor by calling the throw() method on the current Template::Context object,\n\n$context->throw('user.passwd', 'Incorrect Password');\n$context->throw('Incorrect Password');    # type 'undef'\n\nor from Perl code by calling die() with a Template::Exception object,\n\ndie (Template::Exception->new('user.denied', 'Invalid User ID'));\n\nor by simply calling die() with an error string. This is automagically caught and converted to\nan exception of '\"undef\"' type which can then be handled in the usual way.\n\ndie \"I'm sorry Dave, I can't do that\";\n\nNote that the '\"undef\"' we're talking about here is a literal string rather than Perl's \"undef\"\nused to represent undefined values.\n",
            "subsections": []
        },
        "Template Runtime Options": {
            "content": "EVALPERL\nThis flag is used to indicate if \"PERL\" and/or \"RAWPERL\" blocks should be evaluated. It is\ndisabled by default and any \"PERL\" or \"RAWPERL\" blocks encountered will raise exceptions of type\n'\"perl\"' with the message '\"EVALPERL not set\"'. Note however that any \"RAWPERL\" blocks should\nalways contain valid Perl code, regardless of the \"EVALPERL\" flag. The parser will fail to\ncompile templates that contain invalid Perl code in \"RAWPERL\" blocks and will throw a '\"file\"'\nexception.\n\nWhen using compiled templates (see \"Caching and Compiling Options\"), the \"EVALPERL\" has an\naffect when the template is compiled, and again when the templates is subsequently processed,\npossibly in a different context to the one that compiled it.\n\nIf the \"EVALPERL\" is set when a template is compiled, then all \"PERL\" and \"RAWPERL\" blocks will\nbe included in the compiled template. If the \"EVALPERL\" option isn't set, then Perl code will\nbe generated which always throws a '\"perl\"' exception with the message '\"EVALPERL not set\"'\nwhenever the compiled template code is run.\n\nThus, you must have \"EVALPERL\" set if you want your compiled templates to include \"PERL\" and\n\"RAWPERL\" blocks.\n\nAt some point in the future, using a different invocation of the Template Toolkit, you may come\nto process such a pre-compiled template. Assuming the \"EVALPERL\" option was set at the time the\ntemplate was compiled, then the output of any \"RAWPERL\" blocks will be included in the compiled\ntemplate and will get executed when the template is processed. This will happen regardless of\nthe runtime \"EVALPERL\" status.\n\nRegular \"PERL\" blocks are a little more cautious, however. If the \"EVALPERL\" flag isn't set for\nthe *current* context, that is, the one which is trying to process it, then it will throw the\nfamiliar '\"perl\"' exception with the message, '\"EVALPERL not set\"'.\n\nThus you can compile templates to include \"PERL\" blocks, but optionally disable them when you\nprocess them later. Note however that it is possible for a \"PERL\" block to contain a Perl\n\"\"BEGIN { # some code }\"\" block which will always get run regardless of the runtime \"EVALPERL\"\nstatus. Thus, if you set \"EVALPERL\" when compiling templates, it is assumed that you trust the\ntemplates to Do The Right Thing. Otherwise you must accept the fact that there's no bulletproof\nway to prevent any included code from trampling around in the living room of the runtime\nenvironment, making a real nuisance of itself if it really wants to. If you don't like the idea\nof such uninvited guests causing a bother, then you can accept the default and keep \"EVALPERL\"\ndisabled.\n\nOUTPUT\nDefault output location or handler. This may be specified as one of: a file name (relative to\n\"OUTPUTPATH\", if defined, or the current working directory if not specified absolutely); a file\nhandle (e.g. \"GLOB\" or IO::Handle) opened for writing; a reference to a text string to which the\noutput is appended (the string isn't cleared); a reference to a subroutine which is called,\npassing the output text as an argument; as a reference to an array, onto which the content will\nbe push()ed; or as a reference to any object that supports the print() method. This latter\noption includes the \"Apache::Request\" object which is passed as the argument to Apache/modperl\nhandlers.\n\nexample 1 (file name):\n\nmy $template = Template->new({\nOUTPUT => \"/tmp/foo\",\n});\n\nexample 2 (text string):\n\nmy $output   = '';\nmy $template = Template->new({\nOUTPUT => \\$output,\n});\n\nexample 3 (file handle):\n\nopen (TOUT, \"> $file\") || die \"$file: $!\\n\";\nmy $template = Template->new({\nOUTPUT => \\*TOUT,\n});\n\nexample 4 (subroutine):\n\nsub output { my $out = shift; print \"OUTPUT: $out\" }\nmy $template = Template->new({\nOUTPUT => \\&output,\n});\n\nexample 5 (array reference):\n\nmy $template = Template->new({\nOUTPUT => \\@output,\n})\n\nexample 6 (Apache/modperl handler):\n\nsub handler {\nmy $r = shift;\nmy $t = Template->new({\nOUTPUT => $r,\n});\n...\n}\n\nThe default \"OUTPUT\" location be overridden by passing a third parameter to the Template\nprocess() method. This can be specified as any of the above argument types.\n\n$t->process($file, $vars, \"/tmp/foo\");\n$t->process($file, $vars, \\$output);\n$t->process($file, $vars, \\*MYGLOB);\n$t->process($file, $vars, \\@output);\n$t->process($file, $vars, $r);  # Apache::Request\n...\n\nOUTPUTPATH\nThe \"OUTPUTPATH\" allows a directory to be specified into which output files should be written.\nAn output file can be specified by the \"OUTPUT\" option, or passed by name as the third parameter\nto the Template process() method.\n\nmy $template = Template->new({\nINCLUDEPATH => \"/tmp/src\",\nOUTPUTPATH  => \"/tmp/dest\",\n});\n\nmy $vars = {\n...\n};\n\nforeach my $file ('foo.html', 'bar.html') {\n$template->process($file, $vars, $file)\n|| die $template->error();\n}\n\nThis example will read the input files /tmp/src/foo.html and /tmp/src/bar.html and write the\nprocessed output to /tmp/dest/foo.html and /tmp/dest/bar.html, respectively.\n\nSTRICT\nBy default the Template Toolkit will silently ignore the use of undefined variables (a bad\ndesign decision that I regret).\n\nWhen the \"STRICT\" option is set, the use of any undefined variables or values will cause an\nexception to be throw. The exception will have a \"type\" of \"var.undefined\" and a message of the\nform \"undefined variable: xxx\".\n\nmy $template = Template->new(\nSTRICT => 1\n);\n\nDEBUG\nThe \"DEBUG\" option can be used to enable debugging within the various different modules that\ncomprise the Template Toolkit. The Template::Constants module defines a set of \"DEBUGXXXX\"\nconstants which can be combined using the logical OR operator, '\"|\"'.\n\nuse Template::Constants qw( :debug );\n\nmy $template = Template->new({\nDEBUG => DEBUGPARSER | DEBUGPROVIDER,\n});\n\nFor convenience, you can also provide a string containing a list of lower case debug options,\nseparated by any non-word characters.\n\nmy $template = Template->new({\nDEBUG => 'parser, provider',\n});\n\nThe following \"DEBUGXXXX\" flags can be used:\n\nDEBUGSERVICE\nEnables general debugging messages for the Template::Service module.\n\nDEBUGCONTEXT\nEnables general debugging messages for the Template::Context module.\n\nDEBUGPROVIDER\nEnables general debugging messages for the Template::Provider module.\n\nDEBUGPLUGINS\nEnables general debugging messages for the Template::Plugins module.\n\nDEBUGFILTERS\nEnables general debugging messages for the Template::Filters module.\n\nDEBUGPARSER\nThis flag causes the Template::Parser to generate debugging messages that show the Perl code\ngenerated by parsing and compiling each template.\n\nDEBUGUNDEF\nThis option causes the Template Toolkit to throw an '\"undef\"' error whenever it encounters\nan undefined variable value.\n\nDEBUGDIRS\nThis option causes the Template Toolkit to generate comments indicating the source file,\nline and original text of each directive in the template. These comments are embedded in the\ntemplate output using the format defined in the \"DEBUGFORMAT\" configuration item, or a\nsimple default format if unspecified.\n\nFor example, the following template fragment:\n\nHello World\n\nwould generate this output:\n\n## input text line 1 :  ##\nHello\n## input text line 2 : World ##\nWorld\n\nDEBUGALL\nEnables all debugging messages.\n\nDEBUGCALLER\nThis option causes all debug messages that aren't newline terminated to have the file name\nand line number of the caller appended to them.\n\nDEBUGFORMAT\nThe \"DEBUGFORMAT\" option can be used to specify a format string for the debugging messages\ngenerated via the \"DEBUGDIRS\" option described above. Any occurrences of $file, $line or $text\nwill be replaced with the current file name, line or directive text, respectively. Notice how\nthe format is single quoted to prevent Perl from interpolating those tokens as variables.\n\nmy $template = Template->new({\nDEBUG => 'dirs',\nDEBUGFORMAT => '<!-- $file line $line : [% $text %] -->',\n});\n\nThe following template fragment:\n\n[% foo = 'World' %]\nHello [% foo %]\n\nwould then generate this output:\n\n<!-- input text line 2 : [% foo = 'World' %] -->\nHello <!-- input text line 3 : [% foo %] -->World\n\nThe DEBUG directive can also be used to set a debug format within a template.\n\n[% DEBUG format '<!-- $file line $line : [% $text %] -->' %]\n",
            "subsections": []
        },
        "Caching and Compiling Options": {
            "content": "CACHESIZE\nThe Template::Provider module caches compiled templates to avoid the need to re-parse template\nfiles or blocks each time they are used. The \"CACHESIZE\" option is used to limit the number of\ncompiled templates that the module should cache.\n\nBy default, the \"CACHESIZE\" is undefined and all compiled templates are cached. When set to any\npositive value, the cache will be limited to storing no more than that number of compiled\ntemplates. When a new template is loaded and compiled and the cache is full (i.e. the number of\nentries == \"CACHESIZE\"), the least recently used compiled template is discarded to make room\nfor the new one.\n\nThe \"CACHESIZE\" can be set to 0 to disable caching altogether.\n\nmy $template = Template->new({\nCACHESIZE => 64,   # only cache 64 compiled templates\n});\n\nmy $template = Template->new({\nCACHESIZE => 0,   # don't cache any compiled templates\n});\n\nAs well as caching templates as they are found, the Template::Provider also implements negative\ncaching to keep track of templates that are *not* found. This allows the provider to quickly\ndecline a request for a template that it has previously failed to locate, saving the effort of\ngoing to look for it again. This is useful when an \"INCLUDEPATH\" includes multiple providers,\nensuring that the request is passed down through the providers as quickly as possible.\n\nSTATTTL\nThis value can be set to control how long the Template::Provider will keep a template cached in\nmemory before checking to see if the source template has changed.\n\nmy $provider = Template::Provider->new({\nSTATTTL => 60,  # one minute\n});\n\nThe default value is 1 (second). You'll probably want to set this to a higher value if you're\nrunning the Template Toolkit inside a persistent web server application (e.g. modperl). For\nexample, set it to 60 and the provider will only look for changes to templates once a minute at\nmost. However, during development (or any time you're making frequent changes to templates)\nyou'll probably want to keep it set to a low value so that you don't have to wait for the\nprovider to notice that your templates have changed.\n\nCOMPILEEXT\nFrom version 2 onwards, the Template Toolkit has the ability to compile templates to Perl code\nand save them to disk for subsequent use (i.e. cache persistence). The \"COMPILEEXT\" option may\nbe provided to specify a filename extension for compiled template files. It is undefined by\ndefault and no attempt will be made to read or write any compiled template files.\n\nmy $template = Template->new({\nCOMPILEEXT => '.ttc',\n});\n\nIf \"COMPILEEXT\" is defined (and \"COMPILEDIR\" isn't, see below) then compiled template files\nwith the \"COMPILEEXT\" extension will be written to the same directory from which the source\ntemplate files were loaded.\n\nCompiling and subsequent reuse of templates happens automatically whenever the \"COMPILEEXT\" or\n\"COMPILEDIR\" options are set. The Template Toolkit will automatically reload and reuse compiled\nfiles when it finds them on disk. If the corresponding source file has been modified since the\ncompiled version as written, then it will load and re-compile the source and write a new\ncompiled version to disk.\n\nThis form of cache persistence offers significant benefits in terms of time and resources\nrequired to reload templates. Compiled templates can be reloaded by a simple call to Perl's\nrequire(), leaving Perl to handle all the parsing and compilation. This is a Good Thing.\n\nCOMPILEDIR\nThe \"COMPILEDIR\" option is used to specify an alternate directory root under which compiled\ntemplate files should be saved.\n\nmy $template = Template->new({\nCOMPILEDIR => '/tmp/ttc',\n});\n\nThe \"COMPILEEXT\" option may also be specified to have a consistent file extension added to\nthese files.\n\nmy $template1 = Template->new({\nCOMPILEDIR => '/tmp/ttc',\nCOMPILEEXT => '.ttc1',\n});\n\nmy $template2 = Template->new({\nCOMPILEDIR => '/tmp/ttc',\nCOMPILEEXT => '.ttc2',\n});\n\nWhen \"COMPILEEXT\" is undefined, the compiled template files have the same name as the original\ntemplate files, but reside in a different directory tree.\n\nEach directory in the \"INCLUDEPATH\" is replicated in full beneath the \"COMPILEDIR\" directory.\nThis example:\n\nmy $template = Template->new({\nCOMPILEDIR  => '/tmp/ttc',\nINCLUDEPATH => '/home/abw/templates:/usr/share/templates',\n});\n\nwould create the following directory structure:\n\n/tmp/ttc/home/abw/templates/\n/tmp/ttc/usr/share/templates/\n\nFiles loaded from different \"INCLUDEPATH\" directories will have their compiled forms save in\nthe relevant \"COMPILEDIR\" directory.\n\nOn Win32 platforms a filename may by prefixed by a drive letter and colon. e.g.\n\nC:/My Templates/header\n\nThe colon will be silently stripped from the filename when it is added to the \"COMPILEDIR\"\nvalue(s) to prevent illegal filename being generated. Any colon in \"COMPILEDIR\" elements will\nbe left intact. For example:\n\n# Win32 only\nmy $template = Template->new({\nDELIMITER    => ';',\nCOMPILEDIR  => 'C:/TT2/Cache',\nINCLUDEPATH => 'C:/TT2/Templates;D:/My Templates',\n});\n\nThis would create the following cache directories:\n\nC:/TT2/Cache/C/TT2/Templates\nC:/TT2/Cache/D/My Templates\n",
            "subsections": []
        },
        "Plugins and Filters": {
            "content": "PLUGINS\nThe \"PLUGINS\" options can be used to provide a reference to a hash array that maps plugin names\nto Perl module names. A number of standard plugins are defined (e.g. \"table\", \"format\", \"cgi\",\netc.) which map to their corresponding \"Template::Plugin::*\" counterparts. These can be\nredefined by values in the \"PLUGINS\" hash.\n\nmy $template = Template->new({\nPLUGINS => {\ncgi => 'MyOrg::Template::Plugin::CGI',\nfoo => 'MyOrg::Template::Plugin::Foo',\nbar => 'MyOrg::Template::Plugin::Bar',\n},\n});\n\nThe recommended convention is to specify these plugin names in lower case. The Template Toolkit\nfirst looks for an exact case-sensitive match and then tries the lower case conversion of the\nname specified.\n\n[% USE Foo %]      # look for 'Foo' then 'foo'\n\nIf you define all your \"PLUGINS\" with lower case names then they will be located regardless of\nhow the user specifies the name in the USE directive. If, on the other hand, you define your\n\"PLUGINS\" with upper or mixed case names then the name specified in the \"USE\" directive must\nmatch the case exactly.\n\nThe \"USE\" directive is used to create plugin objects and does so by calling the plugin() method\non the current Template::Context object. If the plugin name is defined in the \"PLUGINS\" hash\nthen the corresponding Perl module is loaded via require(). The context then calls the load()\nclass method which should return the class name (default and general case) or a prototype object\nagainst which the new() method can be called to instantiate individual plugin objects.\n\nIf the plugin name is not defined in the \"PLUGINS\" hash then the \"PLUGINBASE\" and/or\n\"LOADPERL\" options come into effect.\n\nPLUGINBASE\nIf a plugin is not defined in the \"PLUGINS\" hash then the \"PLUGINBASE\" is used to attempt to\nconstruct a correct Perl module name which can be successfully loaded.\n\nThe \"PLUGINBASE\" can be specified as a reference to an array of module namespaces, or as a\nsingle value which is automatically converted to a list. The default \"PLUGINBASE\" value\n(\"Template::Plugin\") is then added to the end of this list.\n\nexample 1:\n\nmy $template = Template->new({\nPLUGINBASE => 'MyOrg::Template::Plugin',\n});\n\n[% USE Foo %]    # => MyOrg::Template::Plugin::Foo\nor        Template::Plugin::Foo\n\nexample 2:\n\nmy $template = Template->new({\nPLUGINBASE => [   'MyOrg::Template::Plugin',\n'YourOrg::Template::Plugin'  ],\n});\n\ntemplate:\n\n[% USE Foo %]    # =>   MyOrg::Template::Plugin::Foo\nor YourOrg::Template::Plugin::Foo\nor          Template::Plugin::Foo\n\nIf you don't want the default \"Template::Plugin\" namespace added to the end of the\n\"PLUGINBASE\", then set the $Template::Plugins::PLUGINBASE variable to a false value before\ncalling the new() Template#new() constructor method. This is shown in the example below where\nthe \"Foo\" plugin is located as \"My::Plugin::Foo\" or \"Your::Plugin::Foo\" but not as\n\"Template::Plugin::Foo\".\n\nexample 3:\n\nuse Template::Plugins;\n$Template::Plugins::PLUGINBASE = '';\n\nmy $template = Template->new({\nPLUGINBASE => [   'My::Plugin',\n'Your::Plugin'  ],\n});\n\ntemplate:\n\n[% USE Foo %]    # =>   My::Plugin::Foo\nor Your::Plugin::Foo\n\nLOADPERL\nIf a plugin cannot be loaded using the \"PLUGINS\" or \"PLUGINBASE\" approaches then the provider\ncan make a final attempt to load the module without prepending any prefix to the module path.\nThis allows regular Perl modules (i.e. those that don't reside in the Template::Plugin or some\nother such namespace) to be loaded and used as plugins.\n\nBy default, the \"LOADPERL\" option is set to 0 and no attempt will be made to load any Perl\nmodules that aren't named explicitly in the \"PLUGINS\" hash or reside in a package as named by\none of the \"PLUGINBASE\" components.\n\nPlugins loaded using the \"PLUGINS\" or \"PLUGINBASE\" receive a reference to the current context\nobject as the first argument to the new() constructor. Modules loaded using \"LOADPERL\" are\nassumed to not conform to the plugin interface. They must provide a new() class method for\ninstantiating objects but it will not receive a reference to the context as the first argument.\n\nPlugin modules should provide a load() class method (or inherit the default one from the\nTemplate::Plugin base class) which is called the first time the plugin is loaded. Regular Perl\nmodules need not. In all other respects, regular Perl objects and Template Toolkit plugins are\nidentical.\n\nIf a particular Perl module does not conform to the common, but not unilateral, new()\nconstructor convention then a simple plugin wrapper can be written to interface to it.\n\nFILTERS\nThe \"FILTERS\" option can be used to specify custom filters which can then be used with the\n\"FILTER\" directive like any other. These are added to the standard filters which are available\nby default. Filters specified via this option will mask any standard filters of the same name.\n\nThe \"FILTERS\" option should be specified as a reference to a hash array in which each key\nrepresents the name of a filter. The corresponding value should contain a reference to an array\ncontaining a subroutine reference and a flag which indicates if the filter is static (0) or\ndynamic (1). A filter may also be specified as a solitary subroutine reference and is assumed to\nbe static.\n\n$template = Template->new({\nFILTERS => {\n'sfilt1' =>   \\&staticfilter,      # static\n'sfilt2' => [ \\&staticfilter, 0 ], # same as above\n'dfilt1' => [ \\&dyanamicfilterfactory, 1 ],\n},\n});\n\nAdditional filters can be specified at any time by calling the definefilter() method on the\ncurrent Template::Context object. The method accepts a filter name, a reference to a filter\nsubroutine and an optional flag to indicate if the filter is dynamic.\n\nmy $context = $template->context();\n$context->definefilter('newhtml', \\&newhtml);\n$context->definefilter('newrepeat', \\&newrepeat, 1);\n\nStatic filters are those where a single subroutine reference is used for all invocations of a\nparticular filter. Filters that don't accept any configuration parameters (e.g. \"html\") can be\nimplemented statically. The subroutine reference is simply returned when that particular filter\nis requested. The subroutine is called to filter the output of a template block which is passed\nas the only argument. The subroutine should return the modified text.\n\nsub staticfilter {\nmy $text = shift;\n# do something to modify $text...\nreturn $text;\n}\n\nThe following template fragment:\n\n[% FILTER sfilt1 %]\nBlah blah blah.\n[% END %]\n\nis approximately equivalent to:\n\n&staticfilter(\"\\nBlah blah blah.\\n\");\n\nFilters that can accept parameters (e.g. \"truncate\") should be implemented dynamically. In this\ncase, the subroutine is taken to be a filter 'factory' that is called to create a unique filter\nsubroutine each time one is requested. A reference to the current Template::Context object is\npassed as the first parameter, followed by any additional parameters specified. The subroutine\nshould return another subroutine reference (usually a closure) which implements the filter.\n\nsub dynamicfilterfactory {\nmy ($context, @args) = @;\n\nreturn sub {\nmy $text = shift;\n# do something to modify $text...\nreturn $text;\n}\n}\n\nThe following template fragment:\n\n[% FILTER dfilt1(123, 456) %]\nBlah blah blah\n[% END %]\n\nis approximately equivalent to:\n\nmy $filter = &dynamicfilterfactory($context, 123, 456);\n&$filter(\"\\nBlah blah blah.\\n\");\n\nSee the \"FILTER\" directive for further examples.\n",
            "subsections": []
        },
        "Customisation and Extension": {
            "content": "LOADTEMPLATES\nThe \"LOADTEMPLATES\" option can be used to provide a reference to a list of Template::Provider\nobjects or sub-classes thereof which will take responsibility for loading and compiling\ntemplates.\n\nmy $template = Template->new({\nLOADTEMPLATES => [\nMyOrg::Template::Provider->new({ ... }),\nTemplate::Provider->new({ ... }),\n],\n});\n\nWhen a \"PROCESS\", \"INCLUDE\" or \"WRAPPER\" directive is encountered, the named template may refer\nto a locally defined \"BLOCK\" or a file relative to the \"INCLUDEPATH\" (or an absolute or\nrelative path if the appropriate \"ABSOLUTE\" or \"RELATIVE\" options are set). If a \"BLOCK\"\ndefinition can't be found (see the Template::Context template() method for a discussion of\n\"BLOCK\" locality) then each of the \"LOADTEMPLATES\" provider objects is queried in turn via the\nfetch() method to see if it can supply the required template.\n\nEach provider can return a compiled template, an error, or decline to service the request in\nwhich case the responsibility is passed to the next provider. If none of the providers can\nservice the request then a 'not found' error is returned. The same basic provider mechanism is\nalso used for the \"INSERT\" directive but it bypasses any \"BLOCK\" definitions and doesn't attempt\nis to parse or process the contents of the template file.\n\nIf \"LOADTEMPLATES\" is undefined, a single default provider will be instantiated using the\ncurrent configuration parameters. For example, the Template::Provider \"INCLUDEPATH\" option can\nbe specified in the Template configuration and will be correctly passed to the provider's\nconstructor method.\n\nmy $template = Template->new({\nINCLUDEPATH => '/here:/there',\n});\n\nLOADPLUGINS\nThe \"LOADPLUGINS\" options can be used to specify a list of provider objects (i.e. they\nimplement the fetch() method) which are responsible for loading and instantiating template\nplugin objects. The Template::Context plugin() method queries each provider in turn in a \"Chain\nof Responsibility\" as per the template() and filter() methods.\n\nmy $template = Template->new({\nLOADPLUGINS => [\nMyOrg::Template::Plugins->new({ ... }),\nTemplate::Plugins->new({ ... }),\n],\n});\n\nBy default, a single Template::Plugins object is created using the current configuration hash.\nConfiguration items destined for the Template::Plugins constructor may be added to the Template\nconstructor.\n\nmy $template = Template->new({\nPLUGINBASE => 'MyOrg::Template::Plugins',\nLOADPERL   => 1,\n});\n\nLOADFILTERS\nThe \"LOADFILTERS\" option can be used to specify a list of provider objects (i.e. they implement\nthe fetch() method) which are responsible for returning and/or creating filter subroutines. The\nTemplate::Context filter() method queries each provider in turn in a \"Chain of Responsibility\"\nas per the template() and plugin() methods.\n\nmy $template = Template->new({\nLOADFILTERS => [\nMyTemplate::Filters->new(),\nTemplate::Filters->new(),\n],\n});\n\nBy default, a single Template::Filters object is created for the \"LOADFILTERS\" list.\n\nTOLERANT\nThe \"TOLERANT\" flag is used by the various Template Toolkit provider modules\n(Template::Provider, Template::Plugins, Template::Filters) to control their behaviour when\nerrors are encountered. By default, any errors are reported as such, with the request for the\nparticular resource (\"template\", \"plugin\", \"filter\") being denied and an exception raised.\n\nWhen the \"TOLERANT\" flag is set to any true values, errors will be silently ignored and the\nprovider will instead return \"STATUSDECLINED\". This allows a subsequent provider to take\nresponsibility for providing the resource, rather than failing the request outright. If all\nproviders decline to service the request, either through tolerated failure or a genuine\ndisinclination to comply, then a '\"<resource> not found\"' exception is raised.\n\nSERVICE\nA reference to a Template::Service object, or sub-class thereof, to which the Template module\nshould delegate. If unspecified, a Template::Service object is automatically created using the\ncurrent configuration hash.\n\nmy $template = Template->new({\nSERVICE => MyOrg::Template::Service->new({ ... }),\n});\n\nCONTEXT\nA reference to a Template::Context object which is used to define a specific environment in\nwhich template are processed. A Template::Context object is passed as the only parameter to the\nPerl subroutines that represent \"compiled\" template documents. Template subroutines make\ncallbacks into the context object to access Template Toolkit functionality, for example, to\n\"INCLUDE\" or \"PROCESS\" another template (include() and process() methods, respectively), to\n\"USE\" a plugin (plugin()) or instantiate a filter (filter()) or to access the stash (stash())\nwhich manages variable definitions via the get() and set() methods.\n\nmy $template = Template->new({\nCONTEXT => MyOrg::Template::Context->new({ ... }),\n});\n\nSTASH\nA reference to a Template::Stash object or sub-class which will take responsibility for managing\ntemplate variables.\n\nmy $stash = MyOrg::Template::Stash->new({ ... });\nmy $template = Template->new({\nSTASH => $stash,\n});\n\nIf unspecified, a default stash object is created using the \"VARIABLES\" configuration item to\ninitialise the stash variables.\n\nmy $template = Template->new({\nVARIABLES => {\nid    => 'abw',\nname  => 'Andy Wardley',\n},\n};\n\nPARSER\nThe Template::Parser module implements a parser object for compiling templates into Perl code\nwhich can then be executed. A default object of this class is created automatically and then\nused by the Template::Provider whenever a template is loaded and requires compilation. The\n\"PARSER\" option can be used to provide a reference to an alternate parser object.\n\nmy $template = Template->new({\nPARSER => MyOrg::Template::Parser->new({ ... }),\n});\n\nGRAMMAR\nThe \"GRAMMAR\" configuration item can be used to specify an alternate grammar for the parser.\nThis allows a modified or entirely new template language to be constructed and used by the\nTemplate Toolkit.\n\nSource templates are compiled to Perl code by the Template::Parser using the Template::Grammar\n(by default) to define the language structure and semantics. Compiled templates are thus\ninherently \"compatible\" with each other and there is nothing to prevent any number of different\ntemplate languages being compiled and used within the same Template Toolkit processing\nenvironment (other than the usual time and memory constraints).\n\nThe Template::Grammar file is constructed from a YACC like grammar (using \"Parse::YAPP\") and a\nskeleton module template. These files are provided, along with a small script to rebuild the\ngrammar, in the parser sub-directory of the distribution.\n\nYou don't have to know or worry about these unless you want to hack on the template language or\ndefine your own variant. There is a README file in the same directory which provides some small\nguidance but it is assumed that you know what you're doing if you venture herein. If you grok\nLALR parsers, then you should find it comfortably familiar.\n\nBy default, an instance of the default Template::Grammar will be created and used automatically\nif a \"GRAMMAR\" item isn't specified.\n\nuse MyOrg::Template::Grammar;\n\nmy $template = Template->new({\nGRAMMAR = MyOrg::Template::Grammar->new();\n});\n",
            "subsections": []
        }
    },
    "summary": "Template::Manual::Config - Configuration options",
    "flags": [],
    "examples": [],
    "see_also": []
}