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.05.tar.gz Unpack the archive to create an installation directory. Something like this: zcat Template-Toolkit-1.05.tar.gz | tar xvf - 'cd' into that directory, make, test and install the modules: cd Template-Toolkit-1.05 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-.tar.gz /authors/id/ABW/AppConfig-.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 %] [% user.name %] Output: The cat sat on the mat Me, Myself, I 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 http://www.kfs.org/~abw/ http://www.cre.canon.co.uk/perl VERSION This is version 1.05 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-.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.