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-0.28.tar.gz

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

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

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

        cd Template-Toolkit-0.28
        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 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.005.

    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 and
    two additional scripts.

    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 tpage and ttree scripts are useful utilities for processing
    template documents, or entire content trees, respectively.

        perldoc tpage
        perldoc ttree

OVERVIEW
    The Template Toolkit is a collection of Perl modules which
    collectively implement a fast, powerful and generic template
    processing system. In this context, a template is a text
    document which contains embedded processing "directives". These
    instruct the template processor to perform certain actions such
    as; inserting the value of a variable; processing and including
    another template file or user-defined block; testing some
    condition and generating output of one kind or another
    accordingly; iterating through a set of values; and so on.
    Anything not marked as a template directive is treated as plain
    text and gets passed through unaltered. By default, directives
    look something like this:

       [% INCLUDE header %]

    The "mini-language" that the toolkit uses is designed to be
    clear, concise, regular in structure and simple in syntax. It is
    a specialised language which boasts many powerful features for
    constructing dynamic content but it is *not* a general purpose
    programming language. Instead, it supports a plugin interface
    which allows separate modules of application specific code to be
    written in the language of choice (i.e. Perl, C, C++, etc) and
    then loaded, used and re-used as required.

    This gives you the facility to add any programmable
    functionality you require but without having to write the code
    directly into the document. In other words, it promotes the
    separation of application code (the *implementation*) from the
    user interface (the *presentation*). It tries to keep templates
    clutter-free, concentrating on what the document looks like, and
    hides the implementation specific details of how the various
    items of content are stored, retrieved or calculated.

    Development and subsequent maintenance become easier and less
    error prone when the "back-end" is separated from the "front-
    end". You (or your web designer) can first decide how the
    page(s) should look by creating the output templates, perhaps by
    re-using other common elements that you've already defined for
    your web site such as headers, footers, menus, etc. Then, you
    (or your progammer) can create any Perl code required to
    required to generate the dynamic parts of the content, perhaps
    by using CPAN modules, one of the existing Template Toolkit
    "plugins" or by re-using some code you've previously written for
    another web "application" running on your site.

    The important thing is that the code is developed *separately*
    from the template documents. This is a key feature of the
    Template Toolkit with the emphasis being on moving code *out* of
    documents, rather than moving it *in*. It doesn't matter if you
    put every function in a separate file or every bit of
    application code into one big module - just tell the Template
    Toolkit where to find the code and leave it to handle the rest.
    The new functionality is then available without distraction or
    discourse in any and all of your template documents.

    This isn't the only way to do it. There are times when the "best
    solution" in terms of getting the job done quickly and
    efficiently is to simply embed Perl code directly into the
    document. In those cases, Mark-Jason Dominus' Text::Template
    module, available from CPAN, comes highly recommended. In many
    ways, this is like CGI scripting in reverse. Instead of
    embedding HTML within the Perl script, you are embeddding Perl
    within the HTML document.

    The Template Toolkit promotes the separation of the two in
    attempt to create a more structured approach to constructing
    dynamic content. There's a slight "startup" cost to using this
    approach because, like life in general, it often takes a little
    longer to get yourself properly organised. The payoff comes in
    terms of scalability and subsequent ease of re-use - the more
    you add, the more you benefit from having structure. That's not
    to say that you can't use it in many interesting ways with just
    a single document, but if you only have a single document to
    worry about then the chances are that you haven't got a lot to
    worry about.

    So rather than emphasing the raw programming power embeddable
    within any *single document*, it focuses on tools and techniques
    to help better partition and subsequently re-integrate the
    different components that constitute the *many* documents in a
    system. It offers speed and simplicity in constructing document
    systems and delegates "real programming" to a more powerful,
    general purpose language - Perl.

    There are many benefits to be gained from keeping Perl code
    separate from template documents. You could, for example, write
    a single web application with a dozen different sets of
    templates to represent alternate user interfaces. These would
    represent multiple "views" on the same underlying "model" and
    might differ in layout or design style, contain text only or go
    hard on the graphics, contain HTML frames or not, show "novice"
    or "expert" functionality, allow per-user customisation, present
    an internationalised or localised interface, and so on. On the
    other side of the same coin, you could change your underlying
    code to implement a faster algorithm or more efficient storage
    method, but you wouldn't have to change the template files. They
    still get their "content" from the same "place" and don't need
    to concern themselves with what happens inside each black box.

    The end result is that complex, dynamic content systems can be
    built easily and quickly from a number of small, reusable
    components. Some of these components are template files
    representing user interface "chunks" and others may be data
    structures, library code, user-defined sub-routines or objects
    that implement various functionalities of the system. The
    Template Toolkit's role is to help pull all the different pieces
    together as quickly and simply as possible, hiding as many of
    the unnecessary details as it can.

    The Template Toolkit is ideally suited for generating web
    content, but it is by no means limited or specific to this or
    any other application area. The plugin interface means that it
    doesn't have to be - it can just concentrate on the task of
    constructing documents and doesn't care if you subsequently use
    it to generate HTML, LaTeX, RTF or plain text documents from a
    command-line, CGI script or an in-server web process such as
    Apache/mod_perl using data extracted from a CGI form, defined in
    a file, retrieved from a database or based on what Jim Morrison
    told you in a dream. You choose what do to with it and how to do
    it. Simply load additional functionality as you need it from
    CPAN modules, Template Toolkit plugins, generic web applications
    such as chat rooms, FAQ lists, bulletin boards, etc., or any
    other code you can beg, borrow or write yourself.

    It is worth noting that there is nothing to stop you from
    adopting a well structured approach to content construction
    using Text::Template or one of the other fine template
    processing modules available. Many people do indeed develop
    content using these tools in such a way as to promote
    reusability and maintainability every bit as much as the
    Template Toolkit does. The benefit of using the toolkit is that
    much of this is done for you. You get to reap the benefits of
    template caching (resulting in fast runtime processing),
    automatic error detection and handling, variable localisation
    and namespacing, dynamic loading of external modules, and so on,
    without having to code it yourself or even worry about the
    specifics of implementation. The details are hidden away, the
    directive syntax is simplified and you can get a lot done very
    quickly with the minimum of fuss. The benefit of the
    Text::Template approach is that you have complete control over
    exactly what happens and you can be as structured or as
    unstructured as the task in hand demands. The internal parsing
    and processing method is also extremely efficient and fast,
    being handled by Perl itself.

    The Template Toolkit is a direct descendant of, and replacement
    for the Text::MetaText module. It has been designed and rebuilt
    from scratch based on several years of experience gained from
    developing, supporting and using Text::MetaText and other
    template processing applications and tools. It is an Open Source
    project in which contribution and collaboration are encouraged.

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).

    -   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.

    -   Ideally suited, but not limited to, web content generation.
        Front-end modules and/or scripts provided for use with
        static pages, CGI scripts, Apache/mod_perl handlers, etc.
        Plugin modules available for interfacing to CGI and DBI.

    -   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.

    -   Template language is 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>

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 0.28 of the Template Toolkit.

    It is a stable beta release version preceding the imminent
    release of version 1.0.

    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-1999 Andy Wardley. All Rights Reserved.
    Copyright (C) 1998-1999 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.

