CINXE.COM
About the Template Toolkit
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <title>About the Template Toolkit</title> <link rel="stylesheet" type="text/css" href="/css/blue.css" title="Clear Blue"> <link rel="alternate stylesheet" type="text/css" href="/css/orange.css" title="Clear Orange"> <link rel="alternate stylesheet" type="text/css" href="/css/green.css" title="Clear Green"> <link rel="alternate stylesheet" type="text/css" href="/css/purple.css" title="Clear Purple"> <link rel="alternate stylesheet" type="text/css" href="/css/grey.css" title="Clear Grey"> <!--[if IE 6]> <link rel="stylesheet" type="text/css" href="/css/ie6.css" /> <![endif]--> <link rel="stylesheet" type="text/css" href="/css/print.css" media="print"> <script type="text/javascript" src="/js/tt2.js"></script> <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> <meta name="author" content="Andy Wardley"> <link rel="shortcut icon" href="/images/icons/t.gif" type="image/gif"> </head> <body id="body"> <div id="layout"> <div id="header"> <a href="/index.html" id="logo" title="Click for the Home Page"><span class="alt">TT2 Home Page</span></a> <ul id="trail"> <li class="last"><a href="/about.html">About</a></li> </ul> <div class="controls"> <a href="#" class="menu show" onclick="widescreen_off(); return false" title="Show Menu"> <span class="about">Click to view the menu. It's very nice.</span> </a> <a href="#" class="menu hide" onclick="widescreen_on(); return false" title="Hide Menu"> <span class="about">Click to hide the menu and go all widescreen!</span> </a> <div class="pager"> <a href="/index.html" title="Template Toolkit Home Page" class="go back">Back<span class="about"><strong>Template Toolkit Home Page</strong></span></a> <a href="/index.html" title="Template Toolkit Home Page" class="go up">Up<span class="about"><strong>Template Toolkit Home Page</strong></span></a> <a href="/download/index.html" title="Template Toolkit Downloads" class="go next">Next<span class="about"><strong>Template Toolkit Downloads</strong></span></a> </div> </div> <h1 class="headline">About the Template Toolkit</h1> <a href="http://template-toolkit.org/about.html" class="permalink">http://template-toolkit.org/about.html</a> </div> <div id="page"> <div id="sidebar"> <div id="menu"> <ul class="menu"> <li class="l0 first"><a href="/about.html" class="warm">About</a></li> <li class="l0"><a href="/download/index.html">Download</a></li> <li class="l0"><a href="/docs/index.html">Documentation</a></li> <li class="l0"><a href="/mail.html">Mailing Lists</a></li> <li class="l0 last"><a href="/book.html">Badger Book</a></li> </ul> <div class="foot"></div> </div> <div class="badges"> <a href="http://validator.w3.org/check?uri=referer" class="html_valid badge"></a> <a href="http://jigsaw.w3.org/css-validator/check/referer" class="css_valid badge"></a> <a href="http://wardley.org" class="abw badge"></a> <a href="http://contentity.co.uk/" class="contentity badge"></a> </div> </div> <div id="content"> <div class="section"> <div class="head"> <h1 id="contents" onclick="switch_section(this)" title="Click title to show/hide section content.">Contents</h1> <a href="#body" class="top" title="Back up to the top of the page" >Top</a> <a href="#" class="shut" title="Close section content" onclick="switch_section(this); return false;">Close</a> <a href="#" class="open" title="Open section content" onclick="switch_section(this); return false;">Open</a> </div> <div class="body"> <ul class="toc"> <li class=""><a href="#section_Introduction">Introduction</a></li> <li class=""><a href="#section_Features">Features</a></li> <li class=""><a href="#section_Examples">Examples</a></li> <li class="sub"><a href="#section_Templates_and_Variables">Templates and Variables</a></li> <li class="sub"><a href="#section_Complex_Data">Complex Data</a></li> <li class="sub"><a href="#section_Loops_and_Conditions">Loops and Conditions</a></li> <li class="sub"><a href="#section_Filters_and_Plugins">Filters and Plugins</a></li> </ul> </div> </div> <div class="pod"> <div class="section"> <div class="head"> <h1 id="section_Introduction" onclick="switch_section(this)" title="Click title to show/hide section content.">Introduction</h1> <a href="#body" class="top" title="Back up to the top of the page" >Top</a> <a href="#" class="shut" title="Close section content" onclick="switch_section(this); return false;">Close</a> <a href="#" class="open" title="Open section content" onclick="switch_section(this); return false;">Open</a> </div> <div class="body"> <p> The Template Toolkit is a fast, flexible and highly extensible template processing system. It is free (in both senses: beer and speech) open source software and runs on virtually every modern operating system known to man. It is written in the Perl programming language with certain key elements coded in C for maximum speed. However you don't need to know any Perl (or C) to be able to use it. </p> <p> It is ideally suited, but not limited to, the creation of static and dynamic web content and incorporates various modules and tools to simplify this process. It is mature, robust, reliable and well documented. </p> </div> </div> <div class="section"> <div class="head"> <h1 id="section_Features" onclick="switch_section(this)" title="Click title to show/hide section content.">Features</h1> <a href="#body" class="top" title="Back up to the top of the page" >Top</a> <a href="#" class="shut" title="Close section content" onclick="switch_section(this); return false;">Close</a> <a href="#" class="open" title="Open section content" onclick="switch_section(this); return false;">Open</a> </div> <div class="body"> <p> Here's an overview of some of the Template Toolkit's key features. </p> <ul> <li id="item_1">Fast, powerful and extensible template processing system. </li> <li id="item_2">Powerful presentation language supports all standard templating directives, e.g. variable substitution, includes, conditionals, loops. </li> <li id="item_3">Additional features include output filters, exception handling, macro definition, support for plugin objects and definition of template metadata. </li> <li id="item_4">Full support for complex data types including hashes, lists, objects and subroutine references. </li> <li id="item_5">Provides a clear separation of concerns between content, user interface elements, application code and data. </li> <li id="item_6">Designer-centric front end hides underlying complexity behind simple variable access. </li> <li id="item_7">Programmer-centric back end, allowing application logic and data structures to be built in Perl. </li> <li id="item_8">Templates are compiled to Perl code for maximum runtime efficiency and performance. Compiled templates are cached and can be written to disk in compiled form to achieve cache persistance. </li> <li id="item_9">Well suited to online dynamic web content generation (e.g. Apache/mod_perl). </li> <li id="item_10">Also has excellent support for offline batch processing for generating static pages (e.g. HTML, POD, LaTeX, PostScript, plain text) from source templates. </li> <li id="item_11">Comprehensive documentation including tutorial and reference manuals. </li> <li id="item_12">Fully Open Source and Free </li> </ul> </div> </div> <div class="section"> <div class="head"> <h1 id="section_Examples" onclick="switch_section(this)" title="Click title to show/hide section content.">Examples</h1> <a href="#body" class="top" title="Back up to the top of the page" >Top</a> <a href="#" class="shut" title="Close section content" onclick="switch_section(this); return false;">Close</a> <a href="#" class="open" title="Open section content" onclick="switch_section(this); return false;">Open</a> </div> <div class="body"> <p> Here are some example templates to give you a flavour of what the Template Toolkit can do. See the <a href="/docs/manual/index.html">Template::Manual</a> pages for more comprehensive information about the Template Toolkit and further examples of use. </p> <div class="subsection"> <div class="head"> <h2 id="section_Templates_and_Variables" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">Templates and Variables</h2> <a href="#body" class="top" title="Back up to the top of the page" >Top</a> <a href="#" class="shut" title="Close sub-section content" onclick="switch_subsection(this); return false;">Close</a> <a href="#" class="open" title="Open sub-section content" onclick="switch_subsection(this); return false;">Open</a> </div> <div class="body"> <p> Let's start with the eponymous "Hello World" template. </p> <pre>Hello World!</pre> <p> OK, that's not much of a template, but it does illustrates the first important point that templates are regular text files. Anything that isn't contained inside a template directive tag gets passed through unaltered. </p> <p> So let's add some tags now to make it a proper template. <a href="/docs/manual/Syntax.html">Tags</a> are enclosed between <code>[%</code> and <code>%]</code> and contain <a href="/docs/manual/Directives.html">directives</a> that instruct the Template Toolkit to perform some action. In the next example we'll <a href="/docs/manual/Directives.html#section_INCLUDE">INCLUDE</a> a <code class="file">header</code> at the top, a <code class="file">footer</code> at the bottom, and put the <code>Hello World</code> message in an HTML paragraph. </p> <pre><span class="tt">[% INCLUDE header title="My First Example" %]</span> <p> Hello World! </p> <span class="tt">[% INCLUDE footer copyright="2007 Arthur Dent" %]</span></pre> <p> This demonstrates a second important concept: we can create reusable template components like <code class="file">header</code> and <code class="file">footer</code> that can be loaded into other templates as required with a simple <a href="/docs/manual/Directives.html#section_INCLUDE">INCLUDE</a> directive. Here's what they might look like: </p> <p> <code class="file">header</code> </p> <pre><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN"> <html> <head> <title><span class="tt">[% title %]</span></title> </head> <body> <div id="header"> <a href="/index.html" class="logo" alt="Home Page"></a> <h1 class="headline"><span class="tt">[% title %]</span></h1> </div></pre> <p> <code class="file">footer</code> </p> <pre> <div id="footer"> <div id="copyright"> &copy; <span class="tt">[% copyright %]</span> </div> </div> </body> </html></pre> <p> Notice where the <code>[% title %]</code> variable appears in the <code class="file">header</code> and <code>[% copyright %]</code> in the <code class="file">footer</code>. In this case we're providing the values for <code>title</code> and <code>copyright</code> when we <a href="/docs/manual/Directives.html#section_INCLUDE">INCLUDE</a> the <code class="file">header</code> and <code class="file">footer</code> template components respectively. The Template Toolkit is very flexible about where and how you define <a href="/docs/manual/Variables.html">variables</a>. </p> <p> The only problem with this example is that we've got two separate templates implementing an overall page layout that would be easier to maintain if it were in a single template. Just like this: </p> <p> <code class="file">layout</code> </p> <pre><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN"> <html> <head> <title><span class="tt">[% title %]</span></title> </head> <body> <div id="header"> <a href="/index.html" class="logo" alt="Home Page"></a> <h1 class="headline"><span class="tt">[% title %]</span></h1> </div> <span class="tt">[% content %]</span> <div id="footer"> <div id="copyright"> &copy; <span class="tt">[% copyright %]</span> </div> </div> </body> </html></pre> <p> Now we can use the <a href="/docs/manual/Directives.html#section_WRAPPER">WRAPPER</a> directive to apply the layout template to our "Hello World" page template. </p> <pre><span class="tt">[% WRAPPER layout title = "My First Example" copyright = "2007 Arthur Dent" %]</span> <p> Hello World! </p> <span class="tt">[% END %]</span></pre> <p> Everything between the <code>WRAPPER</code> and <code>END</code> is processed first, and then passed over to the <code class="file">layout</code> template as the <code>content</code> variable, along with the <code>title</code> and <code>copyright</code> variables that we specify explicit values for. In fact, we could have written this simple example like this: </p> <pre><span class="tt">[% INCLUDE layout title = "My First Example" copyright = "2007 Arthur Dent" content = "<p>\n Hello World!\n</p>" %]</span></pre> </div> </div> <div class="subsection"> <div class="head"> <h2 id="section_Complex_Data" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">Complex Data</h2> <a href="#body" class="top" title="Back up to the top of the page" >Top</a> <a href="#" class="shut" title="Close sub-section content" onclick="switch_subsection(this); return false;">Close</a> <a href="#" class="open" title="Open sub-section content" onclick="switch_subsection(this); return false;">Open</a> </div> <div class="body"> <p> The Template Toolkit allows you to define data in a template, to pass it in from a calling Perl program, or to read it from an external source (e.g. a database, XML file, etc) using a plugin module. You can define complex data types that include lists, hash arrays, objects and subroutines. </p> <p> The dot operator is used to access the elements in complex data structures, regardless of what underlying data type they have. For example, <code>person.email</code> and <code>person.name</code> can be used to fetch the <code>email</code> and <code>name</code> items from a <code>person</code> hash array, or to call the <code>email</code> and <code>name</code> methods on a <code>person</code> object. The Template Toolkit takes cares of figuring out what needs to be done to access different data types so that you don't have to worry about it. </p> <p> Here's an example using a simple hash table defined in a template. The comments in the right column following the <code>#</code> indicate the output generated from each line. </p> <pre><span class="tt">[% person = { name = 'Tom' email = 'tom@tt2.org' } %]</span> <span class="tt">[% person.name %]</span> # Tom <span class="tt">[% person.email %]</span> # tom@tt2.org</pre> <p> And here's an example of a list. </p> <pre><span class="tt">[% people = ['Tom', 'Dick', 'Larry'] %]</span> <span class="tt">[% people.0 %]</span> # Tom <span class="tt">[% people.1 %]</span> # Dick <span class="tt">[% people.2 %]</span> # Larry</pre> <p> The Template Toolkit provides a large number of <a href="/docs/manual/VMethods.html">Virtual Methods</a> that can be called against data items to inspect or manipulate the values they contain. For example, we can find out how many items are in a list using <code>.size</code>, or join them into a single item using <code>.join</code>. </p> <pre><span class="tt">[% people.size %]</span> # 3 <span class="tt">[% people.join(', ') %]</span> # Tom, Dick, Larry</pre> </div> </div> <div class="subsection"> <div class="head"> <h2 id="section_Loops_and_Conditions" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">Loops and Conditions</h2> <a href="#body" class="top" title="Back up to the top of the page" >Top</a> <a href="#" class="shut" title="Close sub-section content" onclick="switch_subsection(this); return false;">Close</a> <a href="#" class="open" title="Open sub-section content" onclick="switch_subsection(this); return false;">Open</a> </div> <div class="body"> <p> The next example shows the use of the <a href="/docs/manual/Directives.html#section_FOREACH">FOREACH</a> directive to repeat a block of template content for each item in a list. In this case, the items in the list are hash arrays. </p> <pre><span class="tt">[% people = [ { name = 'Tom', email = 'tom@tt2.org' } { name = 'Dick', email = 'dick@tt2.org' } { name = 'Larry', email = 'larry@tt2.org' } ] %]</span> <ul> <span class="tt">[% FOREACH person IN people %]</span> <li><a href="mailto:<span class="tt">[% person.email %]</span>"><span class="tt">[% person.name %]</span></a></li> <span class="tt">[% END %]</span> </ul></pre> <p> Inside a <code>FOREACH</code> loop, the <code>loop</code> variable can be used to test certain conditions. For example, <code>loop.first</code> and <code>loop.last</code> indicate if we're on the first or last item in the loop respectively. </p> <p> Using the <a href="/docs/manual/Directives.html#section_IF">IF</a> directive in conjunction with <code>loop</code>, we can generate different output for the first and last items in the list. We'll also use <code>loop.count</code> to print the current iteration count next to each item. </p> <pre><span class="tt">[% FOREACH person IN people %]</span> <span class="tt">[% IF loop.first %]</span> <table> <tr> <th>Rank</th> <th>Name</th> <th>Email</th> </tr> <span class="tt">[% END %]</span> <tr> <td><span class="tt">[% loop.count %]</span></td> <td><span class="tt">[% person.name %]</span></td> <td><span class="tt">[% person.email %]</span></td> </tr> <span class="tt">[% IF loop.last %]</span> </table> <span class="tt">[% END %]</span> <span class="tt">[% END %]</span></pre> <p> Conditional <code>IF</code> statements can be combined with <code>ELSIF</code> and <code>ELSE</code> to create more complex branching tests. </p> <pre><span class="tt">[% IF age < 18 %]</span> You are too young. <span class="tt">[% ELSIF age > 65 %]</span> You are too old. <span class="tt">[% ELSE %]</span> Welcome! <span class="tt">[% END %]</span></pre> </div> </div> <div class="subsection"> <div class="head"> <h2 id="section_Filters_and_Plugins" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">Filters and Plugins</h2> <a href="#body" class="top" title="Back up to the top of the page" >Top</a> <a href="#" class="shut" title="Close sub-section content" onclick="switch_subsection(this); return false;">Close</a> <a href="#" class="open" title="Open sub-section content" onclick="switch_subsection(this); return false;">Open</a> </div> <div class="body"> <p> The Template Toolkit provides a number of text <a href="/docs/manual/Filters.html">filters</a> for post-processing blocks of template content. A simple example is the <code>upper</code> filter which converts all text to upper case. </p> <pre><span class="tt">[% FILTER upper %]</span> Hello World! # HELLO WORLD! <span class="tt">[% END %]</span></pre> <p> <a href="/docs/manual/Plugins.html">Plugins</a> are extension modules written in Perl that allow you to incorporate any kind of additional functionality into the Template Toolkit. For example, the <a href="/docs/modules/Template/Plugin/CGI.html">CGI</a> plugin gives you access to the <a href="http://search.cpan.org/search?mode=module&query=CGI">CGI</a> module through which you can access CGI parameters, cookies, and so on. </p> <pre><span class="tt">[% USE CGI %]</span> <span class="tt">[% name = CGI.param('name') or 'World' %]</span> Hello <span class="tt">[% name %]</span>!</pre> <p> Another example is the <a href="http://search.cpan.org/search?mode=module&query=Template%3A%3ADBI">DBI</a> plugin which allows you to query an SQL database and incorporate the results into a template. </p> <pre><span class="tt">[% USE DBI( database = 'dbi:mysql:dbname', username = 'guest', password = 'topsecret' ) %]</span> <ul> <span class="tt">[% FOREACH customer IN DBI.query('SELECT * FROM customers') %]</span> <li><span class="tt">[% customer.name %]</span></li> <span class="tt">[% END %]</span> </ul></pre> </div> </div> </div> </div> </div></div> <br class="clear" /> <div class="pageinfo"> http://template-toolkit.org/about.html last modified 08:49:26 17-Sep-2014 </div> </div> <div id="footer"> <a href="http://opensource.org/" class="osi"></a> <div class="controls"> <div class="pager"> <a href="/index.html" title="Template Toolkit Home Page" class="go back">Back<span class="about"><strong>Template Toolkit Home Page</strong></span></a> <a href="/index.html" title="Template Toolkit Home Page" class="go up">Up<span class="about"><strong>Template Toolkit Home Page</strong></span></a> <a href="/download/index.html" title="Template Toolkit Downloads" class="go next">Next<span class="about"><strong>Template Toolkit Downloads</strong></span></a> </div> </div> <div class="copyright"> Copyright © 1996-2020 <a href="http://wardley.org/">Andy Wardley</a>. All Rights Reserved. </div> <div class="licence"> The <a href="http://template-toolkit.org/">Template Toolkit</a> is <a href="http://opensource.org/">Open Source</a> software. You can redistribute and/or modify it under the terms of the <a href="http://www.opensource.org/licenses/gpl-license.php">GNU Public Licence</a> or the <a href="http://www.opensource.org/licenses/artistic-license.php">Perl Artistic Licence</a>. </div> </div> <div id="palette"> <ul> <li class="first"><a href="#" class="blue" onclick="set_style('Clear Blue')"></a></li> <li><a href="#" class="orange" onclick="set_style('Clear Orange')"></a></li> <li><a href="#" class="green" onclick="set_style('Clear Green')"></a></li> <li><a href="#" class="purple" onclick="set_style('Clear Purple')"></a></li> <li><a href="#" class="grey" onclick="set_style('Clear Grey')"></a></li> </ul> </div> <a href="http://github.com/abw/Template2" class="fork_me"><img src="/images/misc/fork_me_grey.png" alt="Fork me on GitHub"></a> </div> <div id="preload"> <span class="logo"></span> <span class="tab"></span> <span class="hide"></span> <span class="show"></span> <span class="arrow1"></span> <span class="arrow2"></span> <span class="ext"></span> <span class="talk"></span> <span class="menu"></span> <span class="menu_head"></span> <span class="menu_foot"></span> <span class="top"></span> <span class="dotminus1"></span> <span class="dotminus2"></span> <span class="dotplus1"></span> </div> </body> </html>