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.25.tar.gz Unpack the archive to create an installation directory. Something like this: zcat Template-Toolkit-0.25.tar.gz | tar xvf - 'cd' into that directory, make, test and install the modules: cd Template-Toolkit-0.25 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 At present, the Template Toolkit requires Perl 5.005. Efforts will soon be made to support *some* earlier versions (e.g. 5.004). 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 desribing 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 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 (ATML - A Template Markup Language?) 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 and then loaded, used and re-used as required. "Language of choice" can be read as "Perl" in this case, through which you have access to C, C++, and (speaking tentatively) Java. In other words, it helps to promote 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, not how the various items of content are stored, retrieved or calculated. From the perspective of a web designer, for example, they're just bits of text that get inserted into different parts of the page. 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. 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. In other words, the code is portable between templates. This is true if you're using the Template Toolkit to generate static pages off- line, or dynamic pages on-line via CGI script or Apache/mod_perl handler - it's all the same as far as the Template Toolkit is concerned. And because the way it *looks* isn't encoded with what it *does*, you can change the way it looks, or the specific implementation of how it does whatever it does, without affecting the other. There are many benefits. You can write a single web application with a dozen different sets of templates to represent alternate user interfaces. These represent many "views" on the same underlying "model" and may 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 interface localised to other written languages or cultures, and so on. On the other side of the same coin, you can change your underlying code to implement a faster algorithm or more efficient storage method, but you don't have to change the template files because the output doesn't change. They still get their "content" from the same "place" and don't need to concern themselves with what happens inside each black box. Implementation details matter greatly when you're writing programs, but they're rarely important when you're gluing bits of text together to build pages. Page design and layout is a lot easier when you don't have Perl code strewn throughout the document. Writing code is a lot easier when you don't have HTML strewn throught the program. 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. The philosophy behind the toolkit should hopefully now be clearer. It is about speed and simplicity in constructing document systems. It doesn't concern itself with how you write the "clever stuff" that performs whatever process and produces whatever output you desire. It defers that task to a far more powerful, general purpose language - Perl. "Dammit Jim! - I'm a template processor, not a programming language." There are many 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 comes highly recommended (available from CPAN). The Template Toolkit is generally there for the times when you want to build a more structured document *system*. Rather than emphasing the raw programming power embedded within any *single document*, it focusses on tools and techniques to help better partition and subsequently re-integrate the different components that constitute the *many* documents in a system. 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. You may be wondering how this differs from other Perl modules and how it compares to similar dynamic content construction techniques such as Server Side Include (SSI), Cascading Style Sheets (CSL), XML (Extensible Markup Language), and so on. The main points are these: * The Template Toolkit promotes a structured approach to content construction. There's a slight "startup" cost to using this approach because, like life, it always takes a little longer to get yourself properly organised. The payoff comes in terms of scalability. The more you add, the more you benefit from having structure. * The Template Toolkit is not about how much raw programming power you can cram into a document. For that, you simply can't beat directly embedding Perl and processing via a module such as Text::Template. This approach is something like CGI in reverse - instead of putting HTML in your program, you put your program in the HTML. The Template Toolkit instead keeps the two entities separate. * The Template Toolkit doesn't try and do it all. In fact, it tries to do as little as possible, preferring instead to delegate to "Real Perl" and "Real Perl Modules" for "Real Programming" tasks. The toolkit language concerns itself with nothing more than building documents. It doesn't need to be anything like as versatile, powerful, complex or cryptic as Perl. It remains blessedly focussed and bloat- free, and implements as few new wheels as possibly. This is a Good Thing because it means I have less code to maintain and the hubris gets properly shared out. * The Template Toolkit is not specific to any particular application or environment. Nothing in the core toolkit is specific in any way to HTML, CGI or a web server environment. It simply processes text and doesn't concern itself which what that text might finally come to represent: HTML, POD, XML, XSL, LaTeX, RTF, etc. Additional functionality is loaded only as required. You can use it from a command line script, via one of the distribution scripts, tpage and ttree, in a CGI script or in a web or application server environment. Your call. You don't have to change the way you write templates or the way you write code because these things remain independant of the final "delivery method" of the document. 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. - 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 %] [% user.name %] Output: The cat sat on the mat Me, Myself, I 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.25 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-.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.