1 2 Template Toolkit 3 4 Version 2.24 5 6 February 2012 7 8 Copyright (C) 1996-2012 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.24 adds some new text virtual methods and fixes a silly bug in the 48Makefile.PL. 49 50Version 2.23 is a maintenance release which fixes a few bugs, including one 51in the XS Stash which caused problems when using third party modules (e.g. 52DateTime) which use the string-based form of eval. 53 54Version 2.22 is mostly a bug fixing release. The XS Stash now works with 55utf8 data. Tests that were failing on Win32 platforms have been fixed. Pod 56coverage and quality tests have been disabled except for release testing. 57The Autoformat plugin has been moved into a separate distribution. 58 59Version 2.21 featured a complete clean-out of all the old HTML documentation, 60examples, libraries and other cruft that was way out of date and badly 61unloved. A new version of the HTML documentation is available for download 62from http://tt2.org/download/index.html#html_docs. v2.21 also fixes a memory 63leak in the XS Stash. 64 65Version 2.21 also adds the STRICT option which reports the use of undefined 66variable values. The ANYCASE option has been improved so that you can write 67things like 'data.last' without the 'last' bit being interpreted as the LAST 68keyword. The xml filter is also new, providing a slightly more rigourous 69version of the html filter for use in XML documents. 70 71Version 2.20 fixed all known bugs. It also added the Scalar and Assert 72plugins. The HTML documentation, examples, libraries and other bits 73and pieces are still provided with the distribution, but are no longer 74installed by the Makefile.PL. If you want them (and very few people do, 75it seems), then you'll need to dig them out of the distribution by yourself 76(or uncomment the commented-out lines in Makefile.PL that handle the 77installation). This has been done in an effort to simplify the installation 78process. All of the HTML documentation is available online at http://tt2.org/ 79 80Version 2.19 fixed some minor bugs in both Perl and XS versions of the Template 81Stash, and fixed a problem with a test in the test suite failing under Win32. 82It also added the url filter as a version of what the uri filter used to do 83before we fixed it to do the right thing. 84 85Version 2.18 fixes a number of minor bugs. It also includes a modification to 86the parser grammar so that you can write expressions as arguments to 87subroutine, method or vmethod calls. 88 89Versions 2.17 and 2.16 were interim releases by Adam Kennedy who took care of 90some installation problems on Mac OSX while Andy was busy elsewhere. 91 92Version 2.15 is a major maintenance release. It applies all outstanding 93patches and closes all open bugs listed on http://rt.cpan.org/ It 94includes: 95 96 * XS Stash: enhancements include support for tied hashes/arrays 97 and "fallback" methods on objects (e.g. accessing hash and 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, 107 Image, URL and String plugins. Moved DBI, XML and GD plugins 108 into separate distributions. 109 110 * Numerous other bug fixes, enhancements, documentation updates, all 111 described in detail in the Changes file. 112 113More significant is what's not in version 2.15. The DBI plugin has 114been moved into a separate Template-DBI distribution, the GD plugins 115into Template-GD, the XML plugins into Template-XML, and the Latex 116filters into Template-Latex. This has been done in an effort to make 117the Template Toolkit core distribution smaller, cleaner and easier to 118configure and install. 119 120Version 2.14 added Unicode support to TT, a full set of command line 121options for tpage, the 'caller' and 'callers' items to each template 122component, some enhancements to the XML::Simple plugin, and a number 123of minor bug fixes. 124 125See the Changes file for further details of the changes in these and 126earlier releases. 127 128 129GENERAL FEATURES 130---------------- 131 132Some of the key features of the Template Toolkit are listed below. 133See the documentation for further detail. 134 135 * simple but powerful template language 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) 158 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 183DOCUMENTATION 184------------- 185 186The Template Toolkit is provided with enough documentation to keep all 187but the most voracious reader happy for quite some time. 188 189The 'Changes' file in the distribution directory documents all visible 190changes between versions of the Template Toolkit. See the section 191'VERSION COMPATABILITY' below for further details. 192 193The 'TODO' file, also in the distribution directory, lists known bugs, 194planned enhancements and possible new features for future versions. 195 196The 'INSTALL' file covers the configuration and installation process. 197 198The rest of the documentation is distributed in Pod format. The Pod pages 199are installed when you 'make install' and can be viewed using 'perldoc', 200e.g. 201 202 perldoc Template 203 204If you're using a Unix based system then the pages should also be 205converted to manpages suring the 'make install'. Thus, you can also: 206 207 man Template 208 209(the man pages shouldn't have any problems relating to older versions) 210 211The documentation is also available in HTML format at the TT web site: 212 213 http://tt2.org/docs/ 214 215The documentation is now split into several sections. The 'Template' 216page is now much shorter, containing information relating to the 217specifics of using the Template module, and a brief summary of 218everything else. Information relating more generally to the Template 219Toolkit, features, syntax of the template language, plugins and so 220forth, has been split up into a number of Template::Manual::* pages. 221Template::Manual provides the index for the manual. 222 223 perldoc Template::Manual 224 225Individual sections can be viewed as, for example, 226 227 perldoc Template::Manual::Syntax 228 perldoc Template::Manual::Directives 229 perldoc Template::Manual::Plugins 230 231The Template::Tutorial provides an index to the tutorial documents. 232There are currently 2 tutorials, on generating web content, and on 233creating and using data files. 234 235 perldoc Template::Tutorial 236 perldoc Template::Tutorial::Web 237 perldoc Template::Tutorial::Datafile 238 239Each of the various modules that comprise the Template Toolkit has its 240own associated documention. The 'Template::Modules' manpage lists 241these modules along with a brief description of their functions. 242 243 perldoc Template::Modules 244 245See the individual pages for further detail: 246 247 perldoc Template::Context 248 perldoc Template::Parser 249 perldoc Template::Provider 250 251If you're interested in the internals of the Template Toolkit and want 252to know more about how it all works, then you might like to have a look 253at the following: 254 255 perldoc Template::Manual::Internals 256 257This document also contains important information for people wishing 258to hack on the Template Toolkit. 259 260The final bit of good news is that there is now a FAQ for the Template 261Toolkit. 262 263 perldoc Template::FAQ 264 265It's now got a few question in it, and better still, some answers! 266Further contributions welcome. 267 268Most of the documentation is stable and reliable. Where it's not then 269it's usually marked as such. In particular, the documentation for the 270internals (Template::Manual::Internals) and FAQ (Template::FAQ) are 271perpetually under construction. 272 273 274SOURCE CODE 275----------- 276 277The source code for the Template Toolkit is maintained in a public git 278repository at github: 279 280 https://github.com/abw/Template2 281 282If you want to hack on the source code, either to fix a bug or add a feature 283then you should fork the repository, make the changes, commit them, and then 284send me a pull request. See this guide for further information. 285 286 http://help.github.com/send-pull-requests/ 287 288Any non-trivial new features should be discussed on the Template Toolkit 289mailing list first (see below). Don't forget to update the documentation and 290tests where relevant 291 292 293SUPPORT 294------- 295 296The Template Toolkit mailing list provides a forum for discussing 297issues relating to the use and abuse of the Template Toolkit. There 298are a number of knowledgeable and helpful individuals who frequent the 299list (including the author) who can often offer help or suggestions. 300Please respect their time and patience by checking the documentation 301and/or mailing list archives before asking questions that may already 302have been answered. 303 304To subscribe to the mailing list, send an email to: 305 306 templates-request@template-toolkit.org 307 308with the message 'subscribe' in the body. You can also use the web 309interface to subscribe or browse the archives: 310 311 http://mail.template-toolkit.org/mailman/listinfo/templates 312 313A low-volume, moderated mailing list exists for announcements about new 314releases of the Template Toolkit and related products. To subscribe, send 315an email to: 316 317 templates-announce-request@template-toolkit.org 318 319with the message 'subscribe' in the body. A web interface also exists 320for subscription and browsing the archives: 321 322 http://mail.template-toolkit.org/mailman/listinfo/templates-announce 323 324For information about commercial support and consultancy for the Template 325Toolkit, please contact the author. 326 327 328AUTHOR 329------ 330 331The Template Toolkit was written by Andy Wardley <abw@wardley.org> with 332the invaluable assistance and contributions from many other people. 333See Template::Manual::Credits for details. 334 335 336COPYRIGHT 337--------- 338 339Copyright (C) 1996-2012 Andy Wardley. All Rights Reserved. 340 341This is free software; you can redistribute it and/or modify it under 342the same terms as Perl itself. 343 344