Template::TT3::Manual::Introduction - an introduction to TT3

This documentation provides an introduction to version 3 of the Template Toolkit (TT3). It is a work in progress. The code is changing and the docs may not be up to date. Tread carefully.

TT3 is still in development. At present it should be considered alpha quality code at best. For the sake of your own sanity, I would think very carefully before even considering using TT3 in a production system. There are absolutely no guarantees that the things that work today will still be working tomorrow. Consider this fair warning.

There are no CPAN releases of TT3 at present. Nor will there be until such time as TT3 is considered stable enough to warrant a tentative first alpha release. That will be on Tuesday some time shortly after lunch (although we can't say precisely which Tuesday that will be).

Brave Perl hackers who don't mind getting their hands a bit dirty are invited to proceed as follows. First, download and install the latest version of Badger from the source code repository.

$ git clone git://github.com/abw/Badger.git
$ cd Badger
$ perl Makefile.PL
$ make
$ make test
$ sudo make install

Then download and install the latest version of Template::TT3.

$ git clone git://github.com/abw/Template-TT3.git
$ cd Template-TT3
$ perl Makefile.PL
$ make
$ make test
$ sudo make install

Don't worry if a few tests fail for Template-TT3. Failing tests are encouraged at this point in time because they serve as reminders about what things are todo, or have been recently broken. Remember, this is pre-alpha quality code so we're not expecting all tests to pass.

TT3's modules all live in the Template::TT3::* namespace for now. At some point in the future they will be moved "up" a level to occupy the Template namespace, replacing the current Template Toolkit v2 modules. At that time the current TT2 Template::* modules will be moved (or rather, replaced) permanently with their equivalents in Template::TT2::*.

The Template3 module is a new TT3 version of the current TT2 Template module. This is also a temporary measure so that we don't trample on any existing TT2 modules. Template3 will eventually become the new Template module.

First load the Template3 module. Don't forget to use strict and use warnings, too (or use your favourite Perl tool that sets them for you, e.g. use Badger, use Moose, use Modern::Perl, etc.)

use strict;
use warnings;
use Template3;

The process() method continues to be the general purpose all-on-one template processing method. It takes an input, some data, and an output. You can call it as a class method:

Template3->process('hello.tt3', { name => 'World' });

Or you can create an object and call it as an object method:

my $tt3 = Template3->new;
$tt3->process('hello.tt3', { name => 'World' });

Creating an object allows you to specify configuration parameters. For example, the template_path option allows you to specify a location for your templates.

my $tt3 = Template3->new(
    template_path => '/path/to/my/templates'
);

If template_path is specified then TT3 will only serve templates from that directory. Otherwise it will serve templates from anywhere in the filesystem. You can specify multiple locations using as array reference.

my $tt3 = Template3->new(
    template_path => [
        '/path/to/my/templates',
        '/path/to/your/templates',
    ],
);

Andy Wardley http://wardley.org/

Copyright (C) 1996-2009 Andy Wardley. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Template::TT3::Manual