NAME Template Toolkit - a Perl toolkit for processing templates and building template applications. OVERVIEW The Template Toolkit is a collection of Perl modules which collectively implement a fast and powerful template processing system. In this context, a template is a text document which contains embedded processing "directives". These directives instruct the template processor to perform certain actions and collectively constitute the *language* that the toolkit implements. Anything not specially marked as a template directive is treated as plain text and gets passed through intact. You can choose what mark-up tags to use but in the default case, directives are embedded [% like this %]. The toolkit is designed to be fast, flexible and easy to use, allowing you to construct entire content systems from a number of small, reusable components. It can be customised, modified and extended to serve in almost any template-based application. It is ideally suited for generating web content, but it is by no means limited or specific to this or any other application area. Instead, it supports a simple "plugin" interface for dynamically loading extension code to satisfy different requirements. It encourages the clean separation of user interface elements (sub- templates) and code (plugin modules or other Perl objects/code), promoting flexibility, re-use and ease of development and subsequent maintenance. The 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 strongly encouraged. FEATURES - Fast, flexible, generic and open template processing system. - Simple template "micro-language" provides basic functionality to manipulate variables (GET/SET), process other template component files (INCLUDE), iterate through various values (FOREACH) and conditional branching (IF/ELSIF/ELSE). - More complex application code can be developed in Perl (or C, C++, etc) and maintained separately. Template processor binds user code to variables to provide access to application functionality from templates. - This natural extensibility promotes the separation of the application from the interface. 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. - 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. - 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". PREREQUISITES At present, the Template Toolkit requires Perl 5.005. Efforts will soon be made to support *some* earlier versions (e.g. 5.004). OBTAINING AND INSTALLING THE TEMPLATE TOOLKIT The Template Toolkit module bundle is available from CPAN. As the 'perlmod' manual page explains: CPAN stands for the Comprehensive Perl Archive Network. This is a globally replicated collection of all known Perl materials, including hundreds of unbundled modules. [...] For an up-to-date listing of CPAN sites, see http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/ . The module is available as: /authors/id/ABW/Template-Toolkit-.tar.gz Unpack the archive to create an installation directory. Something like this: zcat Template-Toolkit-.tar.gz | tar xvf - 'cd' into that directory, make, test and install the modules: cd Template-Toolkit- perl Makefile.PL make make test make install The 't' sub-directory contains a number of test scripts that are run when a 'make test' is run. You may find some of the examples to be enlightening and others perplexing. 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'; 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 http://www.kfs.org/~abw/ http://www.cre.canon.co.uk/perl VERSION This is version 0.23 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. 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.