Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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