1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
<html>
<head>
<title>Template::Manual::Intro</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">
<link rel="alternate stylesheet" type="text/css" href="../css/print.css" title="Print">
<!--[if IE 6]>
<link rel="stylesheet" type="text/css" href="../css/ie6.css" />
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="../css/ie7.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">
</head>
<body id="body">
<div id="layout">
<div id="header">
<a href="../index.html" id="logo" alt="" title="Click for the Home Page"><span class="alt">TT2 Home Page</span></a>
<ul id="trail">
<li><a href="../manual/index.html">Manual</a></li>
<li class="last"><a href="../manual/Intro.html">Intro</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">
<span class="go back">Back<span class="about">Yeah right, I bet you've love to go back, but you can't.</span></span>
<a href="../manual/index.html" title="Template::Manual" class="go up">Up<span class="about"><h4>Template::Manual</h4>Template Toolkit User Manual</span></a>
<a href="../manual/Syntax.html" title="Template::Manual::Syntax" class="go next">Next<span class="about"><h4>Template::Manual::Syntax</h4>Directive syntax, structure and semantics</span></a>
</div>
</div>
<h1 class="headline">Template::Manual::Intro</h1>
<h2 class="subhead">Introduction to the Template Toolkit</h1>
</div>
<div id="page">
<div id="sidebar">
<a href="../index.html" id="logo"></a>
<div id="menu">
<ul class="menu">
<li class="l0 first"><a href="../manual/index.html" class="warm">Manual</a></li>
<li class="l1"><a href="../manual/Intro.html" class="warm">Intro</a></li>
<li class="l1"><a href="../manual/Syntax.html">Syntax</a></li>
<li class="l1"><a href="../manual/Directives.html">Directives</a></li>
<li class="l1"><a href="../manual/Variables.html">Variables</a></li>
<li class="l1"><a href="../manual/VMethods.html">VMethods</a></li>
<li class="l1"><a href="../manual/Config.html">Config</a></li>
<li class="l1"><a href="../manual/Filters.html">Filters</a></li>
<li class="l1"><a href="../manual/Plugins.html">Plugins</a></li>
<li class="l1"><a href="../manual/Internals.html">Internals</a></li>
<li class="l1"><a href="../manual/Views.html">Views</a></li>
<li class="l1"><a href="../manual/Credits.html">Credits</a></li>
<li class="l0"><a href="../modules/index.html">Modules</a></li>
<li class="l0"><a href="../tools/index.html">Tools</a></li>
<li class="l0"><a href="../tutorial/index.html">Tutorial</a></li>
<li class="l0 last"><a href="../faq/index.html">FAQ</a></li>
</ul>
<div class="foot"></div>
</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>
</div>
<div class="body">
<ul class="toc">
<li class=""><a href="#Introduction">Introduction</a></li>
<li class=""><a href="#The_Template_Perl_Module">The Template Perl Module</a></li>
<li class=""><a href="#Component_Based_Content_Construction">Component Based Content Construction</a></li>
<li class=""><a href="#Data_and_Code_Binding">Data and Code Binding</a></li>
<li class=""><a href="#Advanced_Features_Filters_Macros_Exceptions_Plugins">Advanced Features: Filters, Macros, Exceptions, Plugins</a></li>
<li class=""><a href="#Separating_Presentation_and_Application_Logic">Separating Presentation and Application Logic</a></li>
<li class=""><a href="#Performance">Performance</a></li>
</ul>
</div>
</div>
<div class="pod">
<div class="section">
<div class="head">
<h1 id="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>
</div>
<div class="body">
<p>
The Template Toolkit is a collection of Perl modules which implement a
fast, flexible, powerful and extensible template processing system. It is
most often used for generating dynamic web content, although it can be
used equally well for processing any kind of text documents.
</p>
<p>
At the simplest level it provides an easy way to process template files,
filling in embedded variable references with their equivalent values.
Here's an example of a template.
</p>
<pre>Dear <span class="tt">[% name %]</span>,
It has come to our attention that your account is in
arrears to the sum of <span class="tt">[% debt %]</span>.
Please settle your account before <span class="tt">[% deadline %]</span> or we
will be forced to revoke your Licence to Thrill.
The Management.</pre>
<p>
By default, template directives are embedded within the character
sequences <code>[%</code> ... <code>%]</code> but you can change these
and various other options to configure how the Template Toolkit looks,
feels and works. You can set the <code>INTERPOLATE</code> option, for
example, if you prefer to embed your variables in Perl style:
</p>
<pre>Dear $name,
It has come to our attention that your account is in
arrears to the sum of $debt.
...etc...</pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="The_Template_Perl_Module" onclick="switch_section(this)" title="Click title to show/hide section content.">The Template Perl Module</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <a href="../modules/Template.html">Template</a> Perl module is
the front end to the Template Toolkit for Perl programmers, providing
access to the full range of functionality through a single module with a
simple interface. It loads the other modules as required and instantiates
a default set of objects to handle subsequent template processing
requests. Configuration parameters may be passed to the <a href="../modules/Template.html">Template</a> constructor method, <a href="../modules/Template.html#method_new">new()</a>, which are then used to
configure the generate object.
</p>
<pre>use Template;
my $tt = Template->new({
INCLUDE_PATH => '/usr/local/templates',
INTERPOLATE => 1,
}) || die "$Template::ERROR\n";</pre>
<p>
The <a href="../modules/Template.html">Template</a> object
implements a <a href="../modules/Template.html#method_process">process()</a> method for processing template files or
text. The name of the input template (or various other sources) is passed
as the first argument, followed by a reference to a hash array of
variable definitions for substitution in the template.
</p>
<pre>my $vars = {
name => 'Count Edward van Halen',
debt => '3 riffs and a solo',
deadline => 'the next chorus',
};
$tt->process('letters/overdrawn', $vars)
|| die $tt->error(), "\n";</pre>
<p>
The <a href="../modules/Template.html#method_process">process()</a>
method returns a true value (<code>1</code>) on success and prints the
template output to <code>STDOUT</code>, by default. On error, the <a
href="../modules/Template.html#method_process">process()</a> method
returns a false value (<code>undef</code>). The <a href="../modules/Template.html#method_error">error()</a> method can then be
called to retrieve details of the error.
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Component_Based_Content_Construction" onclick="switch_section(this)" title="Click title to show/hide section content.">Component Based Content Construction</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
A number of special directives are provided, such as <code>INSERT</code>,
<code>INCLUDE</code> and <code>PROCESS</code>, which allow content to be
built up from smaller template components. This permits a modular
approach to building a web site or other content repository, promoting
reusability, cross-site consistency, ease of construction and subsequent
maintenance. Common elements such as headers, footers, menu bars, tables,
and so on, can be created as separate template files which can then be
processed into other documents as required. All defined variables are
inherited by these templates along with any additional "local" values
specified.
</p>
<pre><span class="tt">[% PROCESS header
title = "The Cat Sat on the Mat"
%]</span>
<span class="tt">[% PROCESS menu %]</span>
The location of the missing feline has now been established.
Thank you for your assistance.
<span class="tt">[% INSERT legal/disclaimer %]</span>
<span class="tt">[% PROCESS footer %]</span></pre>
<p>
You can also define a template as a BLOCK within the same file and
PROCESS it just like any other template file. This can be invaluable for
building up repetitive elements such as tables, menus, etc.
</p>
<pre><span class="tt">[% BLOCK tabrow %]</span>
<tr><td><span class="tt">[% name %]</span></td><td><span class="tt">[% email %]</span></td></tr>
<span class="tt">[% END %]</span>
<table>
<span class="tt">[% PROCESS tabrow name="tom" email="tom@here.org" %]</span>
<span class="tt">[% PROCESS tabrow name="dick" email="disk@there.org" %]</span>
<span class="tt">[% PROCESS tabrow name="larry" email="larry@where.org" %]</span>
</table></pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Data_and_Code_Binding" onclick="switch_section(this)" title="Click title to show/hide section content.">Data and Code Binding</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
One of the key features that sets the Template Toolkit apart from other
template processors is the ability to bind template variables to any kind
of Perl data: scalars, lists, hash arrays, sub-routines and objects.
</p>
<pre>my $vars = {
root => 'http://here.com/there',
menu => [ 'modules', 'authors', 'scripts' ],
client => {
name => 'Doctor Joseph von Satriani',
id => 'JVSAT',
},
checkout => sub { my $total = shift; ...; return $something },
shopcart => My::Cool::Shopping::Cart->new(),
};</pre>
<p>
The Template Toolkit will automatically Do The Right Thing to access the
data in an appropriate manner to return some value which can then be
output. The dot operator '<code>.</code>' is used to access into lists
and hashes or to call object methods. The <code>FOREACH</code> directive
is provided for iterating through lists, and various logical tests are
available using directives such as <code>IF</code>, <code>UNLESS</code>,
<code>ELSIF</code>, <code>ELSE</code>, <code>SWITCH</code>,
<code>CASE</code>, etc.
</p>
<pre><span class="tt">[% FOREACH section = menu %]</span>
<a href="<span class="tt">[% root %]</span>/<span class="tt">[% section %]</span>/index.html"><span class="tt">[% section %]</span></a>
<span class="tt">[% END %]</span>
<b>Client</a>: <span class="tt">[% client.name %]</span> (id: <span class="tt">[% client.id %]</span>)
<span class="tt">[% IF shopcart.nitems %]</span>
Your shopping cart contains the following items:
<ul>
<span class="tt">[% FOREACH item = shopcart.contents %]</span>
<li><span class="tt">[% item.name %]</span> : <span class="tt">[% item.qty %]</span> @ <span class="tt">[% item.price %]</span>
<span class="tt">[% END %]</span>
</ul>
<span class="tt">[% checkout(shopcart.total) %]</span>
<span class="tt">[% ELSE %]</span>
No items currently in shopping cart.
<span class="tt">[% END %]</span></pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Advanced_Features_Filters_Macros_Exceptions_Plugins" onclick="switch_section(this)" title="Click title to show/hide section content.">Advanced Features: Filters, Macros, Exceptions, Plugins</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The Template Toolkit also provides a number of additional directives for
advanced processing and programmatical functionality. It supports output
filters (FILTER), allows custom macros to be defined (MACRO), has a
fully-featured exception handling system (TRY, THROW, CATCH, FINAL) and
supports a plugin architecture (USE) which allows special plugin modules
and even regular Perl modules to be loaded and used with the minimum of
fuss. The Template Toolkit is "just" a template processor but you can
trivially extend it to incorporate the functionality of any Perl module
you can get your hands on. Thus, it is also a scalable and extensible
template framework, ideally suited for managing the presentation layer
for application servers, content management systems and other web
applications.
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Separating_Presentation_and_Application_Logic" onclick="switch_section(this)" title="Click title to show/hide section content.">Separating Presentation and Application Logic</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Rather than embedding Perl code or some other scripting language directly
into template documents, it encourages you to keep functional components
(i.e. Perl code) separate from presentation components (e.g. HTML
templates). The template variables provide the interface between the two
layers, allowing data to be generated in code and then passed to a
template component for displaying (pipeline model) or for sub-routine or
object references to be bound to variables which can then be called from
the template as and when required (callback model).
</p>
<p>
The directives that the Template Toolkit provide implement their own mini
programming language, but they're not really designed for serious,
general purpose programming. Perl is a far more appropriate language for
that. If you embed application logic (e.g. Perl or other scripting
language fragments) in HTML templates then you risk losing the clear
separation of concerns between functionality and presentation. It becomes
harder to maintain the two elements in isolation and more difficult, if
not impossible, to reuse code or presentation elements by themselves. It
is far better to write your application code in separate Perl modules,
libraries or scripts and then use templates to control how the resulting
data is presented as output. Thus you should think of the Template
Toolkit language as a set of layout directives for displaying data, not
calculating it.
</p>
<p>
Having said that, the Template Toolkit doesn't force you into one
approach or the other. It attempts to be pragmatic rather than dogmatic
in allowing you to do whatever best gets the job done. Thus, if you
enable the EVAL_PERL option then you can happily embed real Perl code in
your templates within PERL ... END directives.
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="Performance" onclick="switch_section(this)" title="Click title to show/hide section content.">Performance</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The Template Toolkit uses a fast YACC-like parser which compiles
templates into Perl code for maximum runtime efficiency. It also has an
advanced caching mechanism which manages in-memory and on-disk (i.e.
persistent) versions of compiled templates. The modules that comprise the
toolkit are highly configurable and the architecture around which they're
built is designed to be extensible. The Template Toolkit provides a
powerful framework around which content creation and delivery systems can
be built while also providing a simple interface through the Template
front-end module for general use.
</p>
</div>
</div>
</div></div>
<br class="clear" />
<div class="pageinfo">
<a href="http://template-toolkit.org/docs/manual/Intro.html">http://template-toolkit.org/docs/manual/Intro.html</a>
</div>
</div>
<div id="footer">
<a href="http://opensource.org/" class="osi"></a>
<div class="controls">
<div class="pager">
<span class="go back">Back<span class="about"></span></span>
<a href="../manual/index.html" title="Template::Manual" class="go up">Up<span class="about"><h4>Template::Manual</h4></span></a>
<a href="../manual/Syntax.html" title="Template::Manual::Syntax" class="go next">Next<span class="about"><h4>Template::Manual::Syntax</h4></span></a>
</div>
</div>
<div class="copyright">
Copyright © 1996-2012 <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>
</div> </body>
</html>
|
