Template Toolkit

Before installing, ensure your environment meets these requirements:

• Perl: Version 5.006 or later.
• AppConfig: Version 1.56 or above is required if you intend to use the ttree utility (used for parsing command line options and configuration files).

Template Toolkit uses a plugin architecture that allows incorporating functionality from virtually any Perl module. You only need to install external modules if you plan to use specific plugins that depend on them.

To use Template, instantiate a Template object with a configuration hash, define your variables in a hash, and call the process method. By default, the output is printed to STDOUT.

use Template;

my $config = {
    INCLUDE_PATH => '/search/path',
    INTERPOLATE  => 1,
    POST_CHOMP   => 1,
    PRE_PROCESS  => 'header',
    EVAL_PERL    => 1,
};

my $template = Template->new($config);

my $vars = {
    var1  => $value,
    var2  => \%hash,
    var3  => \@list,
    var4  => \&code,
    var5  => $object,
};

my $input = 'myfile.html';

$template->process($input, $vars)
    || die $template->error();

Use the following commands to build and verify your installation:

• make: Builds the modules.
• make test: Runs the test scripts located in the t subdirectory.
• make test TEST_VERBOSE=1: Runs tests with verbose output to see individual test results.

Installation methods for Windows depend on your Perl distribution:

• Strawberry Perl: Use the CPAN module method.
• ActivePerl: Use the Perl Package Manager (ppm) to install pre-compiled packages.
• Manual Installation: If installing manually, you may encounter issues with make. It is recommended to use nmake (available from Microsoft) as a replacement for make in all installation commands.

To install from source, download the gzipped tar archive (e.g., Template-Toolkit-3.102.tar.gz), unpack it, and use the standard Perl installation procedure. Note that Makefile.PL will prompt you for configuration options during the process.

$ tar zxf Template-Toolkit-3.102.tar.gz
$ cd Template-Toolkit-3.102
$ perl Makefile.PL
$ make
$ make test
$ make install

If you do not have administrator privileges, you can install the Template Toolkit to a local directory using the PREFIX option with Makefile.PL.

Important: If you install to a non-standard location, you must update your PERL5LIB environment variable or use use lib in your Perl scripts so that Perl can locate the installed files.

$ perl Makefile.PL PREFIX=/home/abw/

# In your Perl script:
use lib qw( /home/abw/lib/perl5/site_perl/5.10.0 );

If you have the CPAN module client installed, you can install the Template Toolkit directly from the command line.

$ cpan Template

Template::Stash::XS is an XS (C-based) implementation of the Template::Stash module. It is designed to provide a high-performance alternative to the pure-Perl version of Template::Stash by implementing core methods in C.

Key benefits include:

• Speed: It offers approximately twice the speed of the original pure-Perl Template::Stash depending on template size and content.
• Compatibility: It aims to mirror the behavior of the pure-Perl version while providing faster execution for high-frequency operations.

When running perl Makefile.PL, you will be prompted about the XS Stash module. This is a high-speed implementation of Template::Stash written in XS. Using the XS Stash as the default can make the Template Toolkit run significantly faster.

Respond to the following prompts:

• Do you want to build the XS Stash module? [y]
• Do you want to use the XS Stash for all Templates? [n]

You can optimize template performance by enabling compilation and caching. Use the following configuration keys in the new(%config) constructor:

• CACHE_SIZE: The maximum number of compiled templates to keep in memory. If set to undef, all templates are cached.
• COMPILE_EXT: The file extension for compiled template files (e.g., .tmpl_c). If undef, compilation is disabled.
• COMPILE_DIR: The root directory where compiled template files are stored. If undef, compilation is disabled.

Extend template functionality using plugins and filters via the configuration hash:

• PLUGINS: A hash mapping plugin names to Perl packages.
• PLUGIN_BASE: A list of base classes where plugins can be located.
• LOAD_PERL: A boolean flag (default 0). If set, regular Perl modules will be loaded if a named plugin is not found.
• FILTERS: A hash mapping filter names to filter subroutines or factories.

Template::Stash::XS implements core methods like get and set in XS for maximum speed. However, for virtual methods that have not been implemented in XS (such as pop, push, nsort, or sort), the module falls back to using Perl subroutines.

It achieves this by looking up operations in the following hashrefs within the Template::Stash package:

• $HASH_OPS
• $LIST_OPS
• $SCALAR_OPS