Perl Template Toolkit

Preface

Perl Template Toolkit is an introduction to the Template Toolkit. The Template Toolkit is most often used in the creation of web sites, but it can be used as a general text manipulation tool. It is a presentation management system that allows you to separate aspects of presentation from the rest of an application, in the same way that a database allows you to separate storage concerns.

The information in this book is based on Version 2.10 of the Template Toolkit, released in July 2003. The Template Toolkit will continue to evolve. Apart from bug fixes and minor updates, the Version 2.* branch will remain pretty much the same as it is now.

Version 3, expected sometime in 2004, will include new features and some changes to the internal architecture. However, it is an important requirement that new versions of the Template Toolkit are backward-compatible with previous versions wherever possible. Although the Template Toolkit may change in some subtle ways, the basic principles, syntax, and style are here to stay.

Audience

This book should be useful to anyone building and maintaining web sites or other complex content systems. No prior knowledge of Perl, the Template Toolkit, or HTML is required to apply the basic techniques taught in this book. Some of the more advanced topics require some degree of familiarity with the Perl programming language. Readers who understand the basic language constructs and idioms of Perl and who already know how to install and use Perl modules will have no trouble integrating the Template Toolkit into their existing or new projects. Some chapters talk about more specific application areas: HTML, web programming, XML, and SQL, for example. Experience in these areas will make the benefits of the Template Toolkit more readily apparent, but isn’t required.

About this Book

This book is divided into 12 chapters and 1 appendix.

Chapter 1, Getting Started with the Template Toolkit, provides an introduction to the concepts of template processing in general and to the Template Toolkit in particular. It also covers how to install the Template Toolkit on your system and gives a brief tutorial on its use so that you can check that installation is successful. In case it isn’t, the chapter also includes pointers to other sources of information on the Template Toolkit.

Chapter 2, Building a Complete Web Site Using the Template Toolkit, is a tutorial on building a web site using the Template Toolkit. It gives a brief overview of many of the features of the Template Toolkit that are covered in more detail later in the book.

Chapter 3, The Template Language, begins our detailed look at the Template Toolkit. In this chapter, we look at the syntax of the Template Toolkit’s presentation language.

Chapter 4, Template Directives, covers the syntax and use of the many templating directives that can be used from the Template Toolkit.

Chapter 5, Filters, takes a look at filters. These are extensions to the Template Toolkit that allow you to filter your data in various ways before presenting it to your users. This chapter includes a guide to the various standard filters that are included with the Template Toolkit distribution.

Chapter 6, Plugins, looks at the Template Toolkit plugins. Plugins are another way to extend the Template Toolkit by giving your templates access to powerful external modules. This chapter includes a guide to the various standard plugins that are included with the Template Toolkit distribution.

Chapter 7, Anatomy of the Template Toolkit, looks under the covers of the Template Toolkit and examines in some detail how it all works from the inside.

Chapter 8, Extending the Template Toolkit, covers ways to extend the Template Toolkit by writing your own filters and plugins.

Chapter 9, Accessing Databases, looks in detail at writing templates that access data held in various different types of databases.

Chapter 10, XML, looks at using the Template Toolkit to generate XML. It also covers reading XML documents and using their contents from within your templates.

Chapter 11, Advanced Static Web Page Techniques, starts to put together everything we’ve covered in the previous chapters and shows how to build a static web site using the Template Toolkit.

Chapter 12, Dynamic Web Content and Web Applications, extends the example of the previous chapter to add dynamic content to your web site.

Appendix A, describes the configuration options for the Template Toolkit and Apache::Template.

Conventions Used in This Book

The following typographical conventions are used throughout this book:

Constant width

Used for Perl code, Template Toolkit directives, HTML, and code examples.

Italic

Used for filenames, URLs, hostnames, first use of terms, and emphasis.

Tip

Indicates a tip, suggestion, or general note.

Warning

Indicates a warning or caution.

Comments and Questions

Please address comments and questions concerning this book to the publisher:

O’Reilly & Associates, Inc.

1005 Gravenstein Highway North

Sebastopol, CA 95472

[phone] (in the United States or Canada)

[phone] (international/local)

[phone] (fax)

There is a web page for this book, which lists errata, examples, or any additional information. You can access this page at:

http://www.oreilly.com/catalog/perltt

To comment on or ask technical questions about this book, send email to:

[e-mail]

For more information about books, conferences, software, Resource Centers, and the O’Reilly Network, see the O’Reilly web site at:

http://www.oreilly.com

Acknowledgments

This book would not be possible without the contribution and support of many individuals, including friends, family, and the hard-working folks at O’Reilly & Associates, Inc. All three of us wish to thank our production team and, in particular, our editor, Nathan Torkington, for his fine word wrangling and masterful cat herding. We would also like to thank our technical reviewers Chris Devers, Mark Fowler, Andrew Langmead, Martin Portman, and Simon Matthews for their detailed and insightful comments.

Andy Wardley

I’d like to start by thanking Dave, Darren, Nat, and the production team at O’Reilly for turning a bunch of words into a book. I would also like to thank Dom Millar for suggesting a badger for the front cover, and the design team for accommodating us with this beautiful animal.

The Template Toolkit has long since ceased to be a product of my work alone, if indeed it ever was. It owes its success to the dedicated efforts of an extended team of developers, testers, documenters, and users. At the time of this writing, the Template Toolkit documentation lists over sixty contributors who have donated their time and effort in different ways. Our collective thanks go to each of them: Chuck Adams, Stephen Adkins, Ivan Adzhubey, Mark Anderson, Bradley Baetz, Thierry-Michel Barral, Craig Barratt, Stas Bekman, Tony Bowden, Neil Bowers, Leon Brocard, Lyle Brooks, David Cantrell, Piers Cawley, Darren Chamberlain, Eric Cholet, Dave Cross, Chris Dean, Francois Desarmenien, Horst Dumcke, Mark Fowler, Michael Fowler, Axel Gerstmair, Dylan William Hardison, Perrin Harkins, Bryce Harrington, Dave Hodgkinson, Harald Joerg, Colin Johnson, Vivek Khera, Rafael Kitover, Ivan Kurmanov, Hans von Lengerke, Jonas Liljegren, Simon Luff, Paul Makepeace, Gervase Markham, Simon Matthews, Robert McArthur, Craig McLane, Leslie Michael Orchard, Eugene Miretskiy, Tatsuhiko Miyagawa, Keith G. Murphy, Chris Nandor, Briac Pilpré, Martin Portman, Slaven Rezic, Christian Schaffner, Randal L. Schwartz, Paul Sharpe, Ville Skyttä, Doug Steinwand, Michael Stevens, Drew Taylor, Swen Thuemmler, Richard Tietjen, Stathy G. Touloumis, Jim Vaughan, Simon Wilcox, and Chris Winters.

Special thanks are due to Simon Matthews, who has been using and abusing the Template Toolkit and its predecessors from the very start. Countless pints of Guinness have been consumed through long evenings spent discussing the design, development, and general direction of the project. I would also like to thank Martin Portman for the many enjoyable hours we have spent at the whiteboard, engaged in animated conversation and frantic scribbling. Many of the important TT design decisions have been thrashed out in the company of Simon and Martin. Their efforts and input continue to be gratefully received.

I would also like to thank all my other friends and colleagues of past and present at Knowledge Pool, Canon Research Centre Europe, and Fotango, many of whom are listed above. Each of these organizations and the people within them have played important roles in the evolution of the Template Toolkit.

Finally I would like to thank my wife, Sheila, and son, Ben, for their love, patience, and understanding. Writing this book ate up far too much of the time that should have been spent with you.

Darren Chamberlain

I’d like to thank my wife and kids for their help and support, and for being so understanding of the time I’ve spent writing instead of mowing the lawn or playing. This wouldn’t have been possible for me otherwise, and I appreciate it more than they know.

Thanks to Boston.com for having the incredibly sane policy of using the best tool for the job, which means letting me use the Template Toolkit for so many things; to Andrew Langmead, Chris Devers, and Mike Melillo for proofreading, fact-checking, and putting up with me in general; and to Marc Lavallee, for introducing me to TT in first place.

Thanks to Andy for writing the Template Toolkit, which is as fine and versatile a piece of software as I’ve seen in a long time. Andy, Dave, and Nat have all been great—I hope I get to work them again.

And, of course, thanks to everyone who buys the book and keeps O’Reilly (and their fine authors!) afloat.

David Cross

I’d like to thank Andy for developing the Template Toolkit and both Darren and Andy for making the process of writing this book as much fun as it was.

Thanks to the members of the London.pm/TT cabal for first introducing me to the Template Toolkit and convincing me that it was the only templating system that I needed to look at.

Thanks to the various clients and employers who have put up with me leaving the office on time to get on with writing the book. Particular thanks should go to the people at Bibliotech who took pity on me trying to write and work simultaneously and resolved the situation by making me redundant.

Most of this book has been written while listening to music. I’ve found that I write best when listening to either Billy Bragg or any combination of the Waterson/Carthy clan, so thanks to them.

Thank you to Joss Whedon for cancelling “Buffy the Vampire Slayer” while I was working on this book and giving me one less reason to avoid writing.

Thank you to the various friends and family who have ensured that I still have a social life despite my seeming to do my utmost to avoid it.

Thanks, of course, to my parents Jean and John, and to my wife Gill. Their love and support make it all much easier.