NAME
    Template Toolkit - a Perl toolkit for template processing.

OBTAINING AND INSTALLING THE TEMPLATE TOOLKIT
    The Template Toolkit module bundle is available from CPAN as:

        /authors/id/ABW/Template-Toolkit-1.06.tar.gz

    Unpack the archive to create an installation directory. Something like
    this:

        zcat Template-Toolkit-1.06.tar.gz | tar xvf -

    'cd' into that directory, make, test and install the modules:

        cd Template-Toolkit-1.06
        perl Makefile.PL
        make
        make test
        make install

    NOTE: on Win32 systems, Microsoft's 'nmake' appears to be a suitable
    replacement for 'make'.

    The 'make install' will install the module on your system. You may need
    administrator privileges to perform this task. If you install the module
    in a local directory (for example, by executing "perl Makefile.PL
    LIB=~/lib" in the above - see `perldoc ExtUtils::MakeMaker' for full
    details), you will need to ensure that the PERL5LIB environment variable
    is set to include the location, or add a line to your scripts explicitly
    naming the library location:

        use lib '/local/path/to/lib';

PREREQUISITES
    The Template Toolkit requires Perl 5.004 or later.

    The ttree script uses the AppConfig module (version 1.52+) for managing
    configuration information. This is available from CPAN as

        /modules/by-module/AppConfig/AppConfig-<version>.tar.gz
        /authors/id/ABW/AppConfig-<version>.tar.gz       

TOOLKIT CONTENTS
    The Template Toolkit comprises of a number of Perl modules, scripts and
    accompanying documentation.

    The Template module acts as a general interface to the toolkit and
    contains comprehensive documentation describing the toolkit, its usage
    and further sources of reference.

        perldoc Template

    The Template::Tutorial document provides an introduction to the Template
    Toolkit and shows some typical examples of usage.

        perldoc Template::Tutorial

    The tpage and ttree scripts are useful utilities for processing template
    documents, or entire content trees, respectively.

        perldoc tpage
        perldoc ttree

FEATURES
    -   Fast, flexible, generic and open template processing system.

    -   Simple template "mini-language" provides functionality to manipulate
        variables (GET/SET/DEFAULT), process other template component files
        (INCLUDE/PROCESS), iterate through various values (FOREACH),
        conditional branching (IF/UNLESS/ELSIF/ELSE), error handling (CATCH,
        THROW), flow control (BREAK, RETURN, STOP), loading "plugin" code
        (USE) and post-processing (FILTER). Optional PERL sections (disabled
        by default - see EVAL_PERL option) allow Perl code to be directly
        embedded with full interface to the Template Toolkit interface and
        variables.

    -   More complex application code can be developed in Perl (or C, C++,
        etc) and maintained separately as "plugin" code. Template processor
        binds user code to variables to provide access to application
        functionality from templates.

    -   This natural extensibility promotes the separation of the
        application (implementation) from the interface (presentation).
        Template documents remain simple and focussed on rendering the
        interface. Application code can be made more generic by
        concentrating on what the application does, not what it looks like.
        If and when you really need to embed Perl code, you can.

    -   Ideally suited, but not limited to, web content generation. The
        'tpage' and 'ttree' scripts help manage and build entire directory
        trees from source templates, library files and plugin components.
        The Template module can be used directly from CGI scripts,
        Apache/mod_perl handlers, or any other Perl code as a simple
        front-end to the Toolkit. Plugin modules are available for building
        tables, constructing URL's, interfacing to CGI, DBI, XML, DOM, etc.

    -   Template documents parsed by a fast LALR(1) parser which is
        generated from a YACC-like grammar. Parse::Yapp is used to compile
        the grammar. Parser grammar can be modified and re-compiled to
        create custom template languages.

    -   Parsed template documents are compiled to an intermediate form and
        cache. They can subsequently be rendered repeatedly in minimal time.

    -   Stash object manages references to complex external code and data
        and provides a simple template interface via bound variables.

    -   Variables may be partitioned into nested namespaces.

    -   Custom error handling and recovery mechanisms implemented as basic
        exception handling. Users can define template blocks to be processed
        automatically when errors occur and define the subsequent course of
        action.

    -   Iterator objects can be created to handle complex set iteration.
        This is handled transparently by the FOREACH directive.

    -   Provides an extensible framework for other template languages,
        processors and applications, servers, etc.

    -   Template language is largely independent (theoretically at least) of
        the implementation language, platform, operating system, etc.

    -   Extensive documentation, test suite, examples, etc.

    -   `use strict' and `-w' safe. Y2K compliant (no dates used or stored).

    -   Ongoing development and maintenance is part of a general research
        program into web-relevant software tools and techniques at Canon
        Research Centre Europe Ltd.

    -   Fully open source code. Contributions, collaborations, suggestions
        and other feedback welcome.

    -   Mailing list: send email to majordomo@cre.canon.co.uk containing the
        text "subscribe templates".

EXAMPLE
        #!/path/to/perl -w
        use strict;
        use Template;
  
        # create a template processor
        my $tproc = Template->new({ 
            INCLUDE_PATH => '/user/abw/templates', # template search path
        });
  
        # define variables for use in templates
        my $vars  = {
            'animal' => 'cat',
            'place'  => 'mat',
            'list'   => [ 'foo', 'bar', 'baz' ],
            'user'   => { 
                'name'  => 'Me, Myself, I', 
                'email' => 'me@here.com'  
            },
        };
  
        # process a template file, output defaults to STDOUT
        $tproc->process('myfile', $vars)
            || die $tproc->error(), "\n";

    myfile:

        [% INCLUDE header
           title = 'Hello World!'
        %]

        The [% animal %] sat on the [% place %]

        <a href="mailto:[% user.email %]">[% user.name %]</a>

        <ul>
        [% FOREACH item = list %]
           <li>[% item %]
        [% END %]
        </ul>

    Output:

        <!-- ...output from processing 'header' template... -->

        The cat sat on the mat

        <a href="mailto:me@here.com">Me, Myself, I</a>

        <ul>
           <li>foo
           <li>bar
           <li>baz
        </ul>

    Apache/mod_perl handler:

        sub handler {
            my $r    = shift;
            my $file = $r->path_info();  # or some other mapping

            my $template = Template->new({ 
                INCLUDE_PATH => '/where/to/look/for/templates',
                OUTPUT       => $r,
            });

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

            return OK;
        }

MAILING LIST
    A mailing list exists for up-to-date information on the Template Toolkit
    and for following and contributing to the development process. Send
    email to majordomo@cre.canon.co.uk with the following message in the
    body:

        subscribe templates

AUTHOR
    Andy Wardley <abw@cre.canon.co.uk>

        http://www.kfs.org/~abw/
        http://www.cre.canon.co.uk/perl

VERSION
    This is version 1.06 of the Template Toolkit.

    Please consult the Changes file for information about visible changes in
    the Template Toolkit between releases. The TODO file contains details of
    known bugs, planned enhancements, features, fixes, etc.

    The latest version of the Template Toolkit can be downloaded from any
    CPAN site:

        /authors/id/ABW/Template-Toolkit-<version>.tar.gz

    Information regarding interim and development versions is posted to the
    templates mailing list.

COPYRIGHT
    Copyright (C) 1996-2000 Andy Wardley. All Rights Reserved. Copyright (C)
    1998-2000 Canon Research Centre Europe Ltd.

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

