1
2 Template Toolkit
3
4 Version 2.25
5
6 July 2013
7
8 Copyright (C) 1996-2013 Andy Wardley. All Rights Reserved
9
10 This is free software; you can redistribute it and/or
11 modify it under the same terms as Perl itself.
12
13
14INSTALLATION
15------------
16
17If you have the CPAN module installed then you can install the Template
18Toolkit from the command line like so:
19
20 $ cpan Template
21
22Please see the separate INSTALL file for further information on installing
23the Template Toolkit, including what to do if you don't have the CPAN
24module installed, and/or installation on MS Windows.
25
26
27DESCRIPTION
28-----------
29
30The Template Toolkit is a collection of modules which implement a
31fast, flexible, powerful and extensible template processing system.
32It was originally designed and remains primarily useful for generating
33dynamic web content, but it can be used equally well for processing
34any other kind of text based documents: HTML, XML, POD, PostScript,
35LaTeX, and so on.
36
37It can be used as a stand-alone Perl module or embedded within an
38Apache/mod_perl server for generating highly configurable dynamic web
39content. A number of Perl scripts are also provided which can greatly
40simplify the process of creating and managing static web content and
41other offline document systems.
42
43
44WHAT'S NEW?
45-----------
46
47Version 2.25 fixes compatibility with Perl version 5.18 and fixes a numer of
48other minor bugs, typos, etc.
49
50Version 2.24 adds some new text virtual methods and fixes a silly bug in the
51Makefile.PL.
52
53Version 2.23 is a maintenance release which fixes a few bugs, including one
54in the XS Stash which caused problems when using third party modules (e.g.
55DateTime) which use the string-based form of eval.
56
57Version 2.22 is mostly a bug fixing release. The XS Stash now works with
58utf8 data. Tests that were failing on Win32 platforms have been fixed. Pod
59coverage and quality tests have been disabled except for release testing.
60The Autoformat plugin has been moved into a separate distribution.
61
62Version 2.21 featured a complete clean-out of all the old HTML documentation,
63examples, libraries and other cruft that was way out of date and badly
64unloved. A new version of the HTML documentation is available for download
65from http://tt2.org/download/index.html#html_docs. v2.21 also fixes a memory
66leak in the XS Stash.
67
68Version 2.21 also adds the STRICT option which reports the use of undefined
69variable values. The ANYCASE option has been improved so that you can write
70things like 'data.last' without the 'last' bit being interpreted as the LAST
71keyword. The xml filter is also new, providing a slightly more rigourous
72version of the html filter for use in XML documents.
73
74Version 2.20 fixed all known bugs. It also added the Scalar and Assert
75plugins. The HTML documentation, examples, libraries and other bits
76and pieces are still provided with the distribution, but are no longer
77installed by the Makefile.PL. If you want them (and very few people do,
78it seems), then you'll need to dig them out of the distribution by yourself
79(or uncomment the commented-out lines in Makefile.PL that handle the
80installation). This has been done in an effort to simplify the installation
81process. All of the HTML documentation is available online at http://tt2.org/
82
83Version 2.19 fixed some minor bugs in both Perl and XS versions of the Template
84Stash, and fixed a problem with a test in the test suite failing under Win32.
85It also added the url filter as a version of what the uri filter used to do
86before we fixed it to do the right thing.
87
88Version 2.18 fixes a number of minor bugs. It also includes a modification to
89the parser grammar so that you can write expressions as arguments to
90subroutine, method or vmethod calls.
91
92Versions 2.17 and 2.16 were interim releases by Adam Kennedy who took care of
93some installation problems on Mac OSX while Andy was busy elsewhere.
94
95Version 2.15 is a major maintenance release. It applies all outstanding
96patches and closes all open bugs listed on http://rt.cpan.org/ It
97includes:
98
99 * XS Stash: enhancements include support for tied hashes/arrays
100 and "fallback" methods on objects (e.g. accessing hash and
101 list items and calling virtual methods)
102
103 * Virtual Methods: added the scalar.remove, scalar.substr,
104 hash.delete, hash.items, hash.pairs, list.import and list.hash
105 virtual methods. Added support for backreferences to
106 scalar.replace and other improvements to list.push, list.unshift,
107 list.hash, hash.list
108
109 * Plugins: Added Math plugin, Bug fixes and enhancements to File,
110 Image, URL and String plugins. Moved DBI, XML and GD plugins
111 into separate distributions.
112
113 * Numerous other bug fixes, enhancements, documentation updates, all
114 described in detail in the Changes file.
115
116More significant is what's not in version 2.15. The DBI plugin has
117been moved into a separate Template-DBI distribution, the GD plugins
118into Template-GD, the XML plugins into Template-XML, and the Latex
119filters into Template-Latex. This has been done in an effort to make
120the Template Toolkit core distribution smaller, cleaner and easier to
121configure and install.
122
123Version 2.14 added Unicode support to TT, a full set of command line
124options for tpage, the 'caller' and 'callers' items to each template
125component, some enhancements to the XML::Simple plugin, and a number
126of minor bug fixes.
127
128See the Changes file for further details of the changes in these and
129earlier releases.
130
131
132GENERAL FEATURES
133----------------
134
135Some of the key features of the Template Toolkit are listed below.
136See the documentation for further detail.
137
138 * simple but powerful template language
139
140 * promotes a clear separation between application functionality and
141 presentation elements
142
143 * variable substitution allows binding to any Perl data types
144 (scalars, hashes, lists, subs, objects)
145
146 * conditional blocks (IF/UNLESS/ELSIF/ELSE, SWITCH/CASE)
147
148 * loops and iterators (FOREACH, WHILE)
149
150 * file/template inclusion (INSERT, INCLUDE, PROCESS, WRAPPER)
151
152 * definition of local template components (BLOCK)
153
154 * post-processing filters (FILTER)
155
156 * plugin module architecture for easy extensibility (USE)
157
158 * embedded Perl can be optionally enabled (PERL/RAWPERL)
159
160 * full exception handling (TRY/THROW/CATCH/FINAL)
161
162 * user-defined macros (MACRO)
163
164 * definition of template metadata (META)
165
166 * virtual methods for complex data types (e.g. list.size, hash.keys, etc.)
167
168 * numerous configuration options
169
170 * modular OO architecture allows extensive customisation
171
172 * fast LALR(1) parser modules compiles templates according to a
173 YACC-like grammar.
174
175 * templates compiled to Perl code for efficient runtime execution
176
177 * in-memory and on-disk caching of compiled templates
178
179 * simple front end module (Template.pm) for ease of use
180
181 * numerous plugin modules: CGI, DBI, XML, URL, Date, Table, etc
182
183 * standard filters for html, case folding, regex search and replace, etc.
184
185
186DOCUMENTATION
187-------------
188
189The Template Toolkit is provided with enough documentation to keep all
190but the most voracious reader happy for quite some time.
191
192The 'Changes' file in the distribution directory documents all visible
193changes between versions of the Template Toolkit. See the section
194'VERSION COMPATABILITY' below for further details.
195
196The 'TODO' file, also in the distribution directory, lists known bugs,
197planned enhancements and possible new features for future versions.
198
199The 'INSTALL' file covers the configuration and installation process.
200
201The rest of the documentation is distributed in Pod format. The Pod pages
202are installed when you 'make install' and can be viewed using 'perldoc',
203e.g.
204
205 perldoc Template
206
207If you're using a Unix based system then the pages should also be
208converted to manpages suring the 'make install'. Thus, you can also:
209
210 man Template
211
212(the man pages shouldn't have any problems relating to older versions)
213
214The documentation is also available in HTML format at the TT web site:
215
216 http://tt2.org/docs/
217
218The documentation is now split into several sections. The 'Template'
219page is now much shorter, containing information relating to the
220specifics of using the Template module, and a brief summary of
221everything else. Information relating more generally to the Template
222Toolkit, features, syntax of the template language, plugins and so
223forth, has been split up into a number of Template::Manual::* pages.
224Template::Manual provides the index for the manual.
225
226 perldoc Template::Manual
227
228Individual sections can be viewed as, for example,
229
230 perldoc Template::Manual::Syntax
231 perldoc Template::Manual::Directives
232 perldoc Template::Manual::Plugins
233
234The Template::Tutorial provides an index to the tutorial documents.
235There are currently 2 tutorials, on generating web content, and on
236creating and using data files.
237
238 perldoc Template::Tutorial
239 perldoc Template::Tutorial::Web
240 perldoc Template::Tutorial::Datafile
241
242Each of the various modules that comprise the Template Toolkit has its
243own associated documention. The 'Template::Modules' manpage lists
244these modules along with a brief description of their functions.
245
246 perldoc Template::Modules
247
248See the individual pages for further detail:
249
250 perldoc Template::Context
251 perldoc Template::Parser
252 perldoc Template::Provider
253
254If you're interested in the internals of the Template Toolkit and want
255to know more about how it all works, then you might like to have a look
256at the following:
257
258 perldoc Template::Manual::Internals
259
260This document also contains important information for people wishing
261to hack on the Template Toolkit.
262
263The final bit of good news is that there is now a FAQ for the Template
264Toolkit.
265
266 perldoc Template::FAQ
267
268It's now got a few question in it, and better still, some answers!
269Further contributions welcome.
270
271Most of the documentation is stable and reliable. Where it's not then
272it's usually marked as such. In particular, the documentation for the
273internals (Template::Manual::Internals) and FAQ (Template::FAQ) are
274perpetually under construction.
275
276
277SOURCE CODE
278-----------
279
280The source code for the Template Toolkit is maintained in a public git
281repository at github:
282
283 https://github.com/abw/Template2
284
285If you want to hack on the source code, either to fix a bug or add a feature
286then you should fork the repository, make the changes, commit them, and then
287send me a pull request. See this guide for further information.
288
289 http://help.github.com/send-pull-requests/
290
291Any non-trivial new features should be discussed on the Template Toolkit
292mailing list first (see below). Don't forget to update the documentation and
293tests where relevant
294
295
296SUPPORT
297-------
298
299The Template Toolkit mailing list provides a forum for discussing
300issues relating to the use and abuse of the Template Toolkit. There
301are a number of knowledgeable and helpful individuals who frequent the
302list (including the author) who can often offer help or suggestions.
303Please respect their time and patience by checking the documentation
304and/or mailing list archives before asking questions that may already
305have been answered.
306
307To subscribe to the mailing list, send an email to:
308
309 templates-request@template-toolkit.org
310
311with the message 'subscribe' in the body. You can also use the web
312interface to subscribe or browse the archives:
313
314 http://mail.template-toolkit.org/mailman/listinfo/templates
315
316A low-volume, moderated mailing list exists for announcements about new
317releases of the Template Toolkit and related products. To subscribe, send
318an email to:
319
320 templates-announce-request@template-toolkit.org
321
322with the message 'subscribe' in the body. A web interface also exists
323for subscription and browsing the archives:
324
325 http://mail.template-toolkit.org/mailman/listinfo/templates-announce
326
327For information about commercial support and consultancy for the Template
328Toolkit, please contact the author.
329
330
331AUTHOR
332------
333
334The Template Toolkit was written by Andy Wardley <abw@wardley.org> with
335the invaluable assistance and contributions from many other people.
336See Template::Manual::Credits for details.
337
338
339COPYRIGHT
340---------
341
342Copyright (C) 1996-2013 Andy Wardley. All Rights Reserved.
343
344This is free software; you can redistribute it and/or modify it under
345the same terms as Perl itself.
346
347