The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

PUBLIC METHODS

new(\%config)

The new() constructor is called to create and return a new instance of the Template class. This object acts as a front-end processor to the other Template Toolkit modules.

A reference to a hash array may be passed which contains configuration parameters. These may include:

INCLUDE_PATH

The INCLUDE_PATH option specifies one or directories in which to look for template files. Multiple directories can be specified as a reference to a list or as a single string, delimited by ':' ($Template::Cache::PATHSEP) Each item in a list may have additional CACHE parameters associated with it. If no INCLUDE_PATH is specified then the current working directory (i.e. '.') is assumed by default.

    my $cache = Template::Cache->new({
        INCLUDE_PATH => '/user/abw/templates:/user/abw/tmp',
    });
  
    my $cache = Template::Cache->new({
        INCLUDE_PATH => [ '/tmp/templates', '/usr/web/templates' ],
    });
  
    my $template = Template->new({
        INCLUDE_PATH => [ 
            '/user/web/templates/src:/usr/web/templates/elements'
            '/user/web/templates/toodarnbig' => { CACHE => 0 },
        ],
    });
  
    use Template::Cache;
    $Template::Cache::PATHSEP = ';';
    my $template = Template->new({
        INCLUDE_PATH => 'c:/templates;c:/web/templates'
    });
ABSOLUTE_PATHS

This option is enabled by default and allows templates to be specified using absolute paths. In this context, an absolute path is one which starts with '/'. Note that it is generally best to always use '/' as a directory delimiter, regardless of your local operating system convention. Perl will automatically convert forward slashes into the appropriate character.

Any false value will disable the option. In this case, any attempt to process a template file by specifying an absolute path will generate an error in the form of a 'file' exception (see CATCH). Files specified with a leading period (e.g. './foo/bar.html') are treated as relative to the current working directory. All other files are considered relative to one of the INCLUDE_PATH directories.

    # ABSOLUTE_PATHS are enabled by default
    $template->process("/slash/bang/wallop")          # OK
        || die $template->error();

    # in a template file, it would look like this
    [% INCLUDE /slash/bang/wallop %]                  # OK

    # this time we'll disable them
    my $t2 = Template->new({ ABSOLUTE_PATHS => 0 });

    $t2->process("foo/bar.html");                     # OK 
        || die $t2->error();

    $t2->process("/foo/bar.html")      # FAILS with 'file' exception
        || die $t2->error();           # reports

    # nope, this would barf
    [% INCLUDE /foo/bar.html %]        # FAILS with 'file' exception
PRE_DEFINE

A reference to a hash of variables and values that should be pre-defined for use in every template processed via the process() method. The original values are restored each time process() is called.

    my $template = Template->new({
        PRE_DEFINE => {
            'server'    => 'www.myorg.com',
            'help'      => 'help/helpndx.html',
            'images'    => '/images'
            'copyright' => '(C) Copyright 1999',
            'userlist'  => [ 'tom', 'dick', 'harry'   ],
            'myorg'     => { 'name' => 'My Org. Inc.', 
                             'tel'  => '555-1234'     },
            'icon'      => { 'prev' => 'prevbutton', 
                             'next' => 'nextbutton'   },
      }
  });
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. Variables should be prefixed by a '$' to identify them. Curly braces 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">
PRE_PROCESS, POST_PROCESS

These values may be set to contain the names 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 the INCLUDE or PROCESS tags. The PRE_PROCESS and POST_PROCESS are evaluated in the same variable context as the main document and so may define, update or delete variables for subseqent use.

PRE_CHOMP, POST_CHOMP

These values set the chomping options for the parser. With POST_CHOMP set true, 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.

With PRE_CHOMP set true, 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.

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

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

The '-' characters activate both PRE_CHOMP and POST_CHOMP for the one directive '[%- name -%]'. Thus, the template will be processed as if written:

    [% FOREACH user = userlist %][% user %][% END %]

Similarly, '+' characters can be used to disable PRE- or POST-CHOMP (i.e. leave the whitespace/newline intact) options on a per-directive basis.

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

With POST_CHOMP set on, the above example would be parsed as if written:

    [% FOREACH user = userlist %]User: [% user %]
    [% END %]
START_TAG, END_TAG, TAG_STYLE

The START_TAG and END_TAG options are used to specify character sequences or regular expressions that mark the start and end of a template directive. 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->new({ 
        START_TAG => quotemeta('<+'),
        END_TAG   => quotemeta('+>'),
    });

example:

    <+ INCLUDE foobar +>

The TAG_STYLE option can be used to set both according to pre-defined tag styles. Available styles are:

    regular   [% ... %]      (recommended)
    percent   %% ... %%      (Text::MetaText compatibility)
    default   [% ... %] or %% ... %%

The default style (TAG_STYLE => 'default') allows either of the 'regular' or 'percent' tags to be used (START_TAG = '[\[%]%', END_TAG = '%[\]%]') Any values specified for START_TAG and/or END_TAG will over-ride those defined by a TAG_STYLE.

See also the TAGS directive which allows directive tags to set from within a template and act on a per-file basis.

CASE

The Template Toolkit treats all variables with case sensitivity. Thus, the variable 'foo' is different from 'Foo' and 'FOO'. Reserved words, by default, may be specified in either case, but are usually UPPER CASE by convention.

    [% INCLUDE foobar %]
    [% include foobar %]

One side-effect of this is that you cannot use a variable of the same name as a reserved word such as 'include', 'error', 'foreach', etc.

Setting the CASE option to any true value will cause the parser to only consider UPPER CASE words as reserved words. Thus, 'ERROR' remains a reserved word, but 'error', 'Error', 'ERRoR', etc., may all be used as variables.

The only exception to this rule are the 'and', 'or' and 'not' operators which can always be expressed in lower, or indeed any case.

PLUGIN_BASE

This option allows you to define a base package for plugin objects loaded and used via the USE directive. The default value is 'Template::Plugin'. Periods in a plugin name are converted to '::' and the name is appended to the PLUGIN_BASE. Thus the following directive:

    [% USE Magic.Wand %]

Would request and instantiate and object from the plugin module 'Template::Plugin::Magic::Wand'.

Specifying a new PLUGIN_BASE will cause the processor to use that package name before falling back on the default 'Template::Plugin'.

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

In the above example, the [% USE Magic.Wand %] directive, would resolve to 'MyOrg::Template::Plugin::Magic::Wand' or 'Template::Plugin::Magic::Wand' in that order. Thus, a module defined in a 'local' PLUGIN_BASE will be used in preference to the default Template Toolkit equivalent. In other words, the default 'Template::Plugin' location is always searched, but after any user defined values.

PLUGINS

The PLUGINS option may be specified as a reference to a hash pre-defining plugin objects for the USE directive. Each key in the hash represents a plugin name and the corresponding value, a package name or object which should be used to construct new instances of the plugin object.

    use MyOrg::Template::Plugin::Womble;
    use Template::Plugin::DBI;         # available soon...
  
    my $dbi_factory = Template::Plugin::DBI->new();
  
    my $template->new({ 
        PLUGINS => {
          'womble' => 'MyOrg::Template::Plugin::Womble',
          'dbi'    =>  $dbi_factory,
        }
    });

The new() method is called against the PLUGINS value when a plugin is USE'd. Thus, an entry that specifies a package name will caused instances of that plugin to be created as follows:

    [% USE womble %] 
       ==> MyOrg::Template::Plugin::Womble->new($context);

A reference to the Template::Context object in which the plugin will run is passed as the first parameter. The plugin object may store this reference and subsequently use it to control the template process via it's public interface. This gives plugin objects access to the full functionality of the Template Toolkit.

Any parameters specified in parenthesis after the plugin name will be passed to the new() constructor.

    [% USE womble('Tomsk') %] 
       ==> MyOrg::Template::Plugin::Womble->new($context, 'Tomsk');

The PLUGINS value may also contain an object reference. In identical fashion to the above, the new() method is called against the object, allowing it to act as a constructor object or 'prototype' for other instances of the same, or other objects.

    [% USE dbi('dbase_xyz') %]
      ==> $dbi_factory->new($context, 'dbase_xyz');

This approach facilitates the easy implementation and use of plugins that act as singletons (one instance only) or share some state information, such as cached database handles in the DBI example shown here.

Simon Matthews <sam@knowledgepool.com> is currently working on the DBI plugin for the Template Toolkit.

When a plugin is requested via the USE directive that is not specified in the PLUGINS hash, the dynamic loading procedure described under PLUGIN_BASE above will be used. If a module is successfully loaded, the load() sub-routine in that package is called and should return the package name itself (i.e. simply return the first parameter) or an object reference which is then stored and used in the PLUGINS hash as described above.

FILTERS

The FILTERS option may contain a reference to a hash defining additional filter types. Each key represents a filter name and the value should contain a CODE reference which will be called when the relevant FILTER directive is encountered, passing any additional parameters specified. This sub-routine is expected to act as a factory and construct a closure, or return a reference to some other code, which will be responsible for filtering the text.

    $tproc = Template->new({
        FILTERS => {
            'microjive' => sub { \&microjive },
            'censor'    => \&make_censor_filter,
        },
    });
  
    # 'static' filter which never takes params (like 'html')
    sub microjive {
        my $text = shift;
        $text =~ s/microsoft/The 'Soft/sig;
        $text;
    }
    
    # factory for 'dynamic' filters which can take params
    sub make_censor_filter {
        my @forbidden = @_;
        return sub {
            my $text = shift;
            foreach my $word (@forbidden) {
                $text =~ s/$word/**CENSORED**/sig;
            }
            return $text;
        }
    }

Example:

    [% FILTER microjive %] 
    The "Halloween Document", leaked to Eric Raymond 
    from an insider at Microsoft, demonstrated...
    [% END %]              
  
    [% FILTER censor('nuclear') %]
    Airkraft were forced to fly in nuclear winds 
    but still managed an excellent performance.
    [% END %]

Output:

    The "Halloween Document", leaked to Eric Raymond 
    from an insider at The 'Soft, demonstrated...

    Airkraft were forced to fly in **CENSORED** winds 
    but still managed an excellent performance.
OUTPUT_PATH

This option can be used to define a directory to which output files should be written. By default, output is sent to STDOUT, but may be directed to a file by specifying the OUTPUT option or by passing a third parameter to the process() method. The default value for OUTPUT_PATH is '.', representing the current working directory.

    $tproc = Template->new({
        INCLUDE_PATH => '/tmp/src',
        OUTPUT_PATH  => '/tmp/dest',
    });

    my $params = { 'baz' => 'Qux' };

    foreach $file ('foo', 'bar') {
        $tproc->process($file, $params, $file)
            || warn "Error in $file: ", $tproc->error(), "\n";
    }

This example would process the files /tmp/src/foo and /tmp/src/bar, writing the output to /tmp/dest/foo and /tmp/dest/bar respectively.

OUTPUT, ERROR

The OUTPUT and ERROR options may be specified to redirect template output and/or error messages. The values for these options may be one of; a plain string indicating a filename which will be opened (relative to OUTPUT_PATH) and written to; a file GLOB opened ready for output; a reference to a scalar to which output/error is appended; or any object reference which implements a 'print' method. This final option allows IO::Handle, Apache::Request, or other such objects to be passed in directly.

    my $output = '';

    my $template = Template->new({
        OUTPUT => \$output,
        ERROR  => sub { print STDERR "Most Bogus Error: ", @_ }
    };

In an Apache/mod_perl handler:

    sub handler {
        my $r    = shift;
        my $file = $r->path_info();

        my $template = Template->new({ OUTPUT => $r });

        $template->process($file) || do {
            $r->log_reason($template->error());
            return SERVER_ERROR;
        };

        return OK;
    }

The redirect() method can be subsequently called to define new output or error options.

CATCH

The CATCH option may be used to specify a hash array of error handlers which are used when a run time error condition occurs. Each key in the hash represents an error type. The Template Toolkit generates the following error types which have corresponding ERROR_XXX constants.

    undef    - a variable was undefined or evaluated undef
    file     - file find/open/parse error

User code may generate further errors of any types and custom handlers may be provided to trap them. A handler, defined as the related value in the CATCH configuration hash may be one of the STATUS_XXXX constants defined in Template::Constants (e.g. STATUS_OK, STATUS_STOP) or a code reference which is called when an error occurs. The handler is passed a reference to the context ($self) and the error type and info. The return value should be one of the aforementioned constants or a Template::Exception object.

    use Template qw( :error );

    my $template = Template->new({
        CATCH => {
            ERROR_UNDEF => STATUS_OK,
            ERROR_FILE  => sub { 
                my ($context, $type, $info) = @_;
                $context->output("FILE ERROR: $info");
                return STATUS_OK; 
            },
        }
    });

A 'default' handler may be provided to catch any exceptions not explicitly caught by their own handler. This is equivalent to defining a CATCH block without specifying an error type:

    [% CATCH %]
    Caught '[% e.type %]' exception:
      [% e.info %]
    [% END %]
PARSER, GRAMMAR

The PARSER and GRAMMAR configuration items can be used to specify an alternate parser or grammar for the parser. Otherwise an instance of the default Template::Parser/Template::Grammar will be created and used as required.

See the parser sub-directory of the Template Toolkit distribution for further information on compiling and using your own grammars (some parser expertise required).

    use Template;
    use MyTemplate::MyGrammar;

    my $template = Template->new({ 
        GRAMMAR = MyTemplate::MyGrammar->new();
    });
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 permit such recursion.

CACHE

The CACHE item can be used to specify an alternate cache object to handle loading, compiling and caching of template documents. A default Template::Cache object is created otherwise. See Template::Cache for further information.

process($template, \%vars, $output, $error)

The process() method is called to process a template. The first parameter, $template, indicates the template and may be a simple SCALAR containing a filename (relative to INCLUDE_PATH), a reference to a SCALAR which contains the template text or a reference to a GLOB (e.g. \*MYFILE) or IO::Handle or sub-class from which the template is read.

    $file = 'hworld.html'
    $text = "[% INCLUDE header %]\nHello world!\n[% INCLUDE footer %]"

    $template->process($file)
        || die $template->error(), "\n";

    $template->process(\$text)
        || die $template->error(), "\n";

    $template->process(\*DATA)
        || die $template->error(), "\n";

    __END__
    [% INCLUDE header %]    
    Hello World!
    [% INCLUDE footer %]

The optional second parameter may be a reference to a hash array containing variables and values which should be available in the template. These are applied in addition to (and may temporarily modify previous values for) the PRE_DEFINE variables.

Any output generated by processing the template will be sent to the current output stream which is STDOUT by default. Errors are similarly directed to the error stream or STDERR. The optional third and fourth parameters may be used to specify alternate output and error locations for the processing of this template file only, temporarily over-riding any existing OUTPUT and ERROR values (existing file handles remain open and intact). See redirect() below for information on what the values may contain.

The method returns 1 if the template was successfully processed. This includes templates that were ended by a STOP or RETURN directive If an uncaught error occurs, the method returns 0. A relevant error message can then be returned by calling the error() method.

The name of the template file is stored in the template variable 'filename'. This will not be the case if a 'filename' variable has been otherwise defined, or if the $template specified is a reference and does not represent a filename.

  This file: [% filename %]

redirect($what, $where)

The redirect() method can be called to redirect the output or error stream for the template processing system. Redirections can also be established when the object is created with the OUTPUT and ERROR options.

This method simply delegates to the underlying Template::Context object(). The first parameter should specify 'output' or 'error' (defined as the constants TEMPLATE_OUTPUT and TEMPLATE_ERROR in Template::Constants). The second parameter should contain a file name (relative to OUTPUT_PATH), a reference to a scalar variable to which output is appended, a code reference which is called to handle output, or any object that supports a print method.

error()

The error() method returns any error message generated by the previous call to the process() method.

If no error occurred, the method returns a numerical value representing the return code of the last directive processed. This will generally be STATUS_OK (0), STATUS_STOP or STATUS_RETURN. Constants representing the values are defined in Template::Constants.