Commit | Line | Data |
3fea05b9 |
1 | #============================================================= -*-perl-*- |
2 | # |
3 | # Template::Manual::Intro |
4 | # |
5 | # AUTHOR |
6 | # Andy Wardley <abw@wardley.org> |
7 | # |
8 | # COPYRIGHT |
9 | # Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. |
10 | # |
11 | # This module is free software; you can redistribute it and/or |
12 | # modify it under the same terms as Perl itself. |
13 | # |
14 | #======================================================================== |
15 | |
16 | =head1 NAME |
17 | |
18 | Template::Manual::Intro - Introduction to the Template Toolkit |
19 | |
20 | =head1 Introduction |
21 | |
22 | The Template Toolkit is a collection of Perl modules which implement a |
23 | fast, flexible, powerful and extensible template processing system. |
24 | It is most often used for generating dynamic web content, although it can |
25 | be used equally well for processing any kind of text documents. |
26 | |
27 | At the simplest level it provides an easy way to process template |
28 | files, filling in embedded variable references with their equivalent |
29 | values. Here's an example of a template. |
30 | |
31 | Dear [% name %], |
32 | |
33 | It has come to our attention that your account is in |
34 | arrears to the sum of [% debt %]. |
35 | |
36 | Please settle your account before [% deadline %] or we |
37 | will be forced to revoke your Licence to Thrill. |
38 | |
39 | The Management. |
40 | |
41 | By default, template directives are embedded within the character |
42 | sequences C<[%> ... C<%]> but you can change these and various other |
43 | options to configure how the Template Toolkit looks, feels and works. |
44 | You can set the C<INTERPOLATE> option, for example, if you prefer to |
45 | embed your variables in Perl style: |
46 | |
47 | Dear $name, |
48 | |
49 | It has come to our attention that your account is in |
50 | arrears to the sum of $debt. |
51 | |
52 | ...etc... |
53 | |
54 | =head1 The Template Perl Module |
55 | |
56 | The L<Template> Perl module is the front end to the Template Toolkit for Perl |
57 | programmers, providing access to the full range of functionality through a |
58 | single module with a simple interface. It loads the other modules as required |
59 | and instantiates a default set of objects to handle subsequent template |
60 | processing requests. Configuration parameters may be passed to the L<Template> |
61 | constructor method, L<new()|Template#new()>, which are then used to |
62 | configure the generate object. |
63 | |
64 | use Template; |
65 | |
66 | my $tt = Template->new({ |
67 | INCLUDE_PATH => '/usr/local/templates', |
68 | INTERPOLATE => 1, |
69 | }) || die "$Template::ERROR\n"; |
70 | |
71 | The L<Template> object implements a L<process()|Template#process()> method for |
72 | processing template files or text. The name of the input template (or various |
73 | other sources) is passed as the first argument, followed by a reference to a |
74 | hash array of variable definitions for substitution in the template. |
75 | |
76 | my $vars = { |
77 | name => 'Count Edward van Halen', |
78 | debt => '3 riffs and a solo', |
79 | deadline => 'the next chorus', |
80 | }; |
81 | |
82 | $tt->process('letters/overdrawn', $vars) |
83 | || die $tt->error(), "\n"; |
84 | |
85 | The L<process()|Template#process()> method returns a true value (C<1>) on success |
86 | and prints the template output to C<STDOUT>, by default. On error, the |
87 | L<process()|Template#process()> method returns a false value (C<undef>). |
88 | The L<error()|Template#error()> method can then be called to retrieve |
89 | details of the error. |
90 | |
91 | =head1 Component Based Content Construction |
92 | |
93 | A number of special directives are provided, such as C<INSERT>, C<INCLUDE> and |
94 | C<PROCESS>, which allow content to be built up from smaller template |
95 | components. This permits a modular approach to building a web site or other |
96 | content repository, promoting reusability, cross-site consistency, ease of |
97 | construction and subsequent maintenance. Common elements such as headers, |
98 | footers, menu bars, tables, and so on, can be created as separate template |
99 | files which can then be processed into other documents as required. All |
100 | defined variables are inherited by these templates along with any additional |
101 | "local" values specified. |
102 | |
103 | [% PROCESS header |
104 | title = "The Cat Sat on the Mat" |
105 | %] |
106 | |
107 | [% PROCESS menu %] |
108 | |
109 | The location of the missing feline has now been established. |
110 | Thank you for your assistance. |
111 | |
112 | [% INSERT legal/disclaimer %] |
113 | |
114 | [% PROCESS footer %] |
115 | |
116 | You can also define a template as a BLOCK within the same file and |
117 | PROCESS it just like any other template file. This can be invaluable |
118 | for building up repetitive elements such as tables, menus, etc. |
119 | |
120 | [% BLOCK tabrow %] |
121 | <tr><td>[% name %]</td><td>[% email %]</td></tr> |
122 | [% END %] |
123 | |
124 | <table> |
125 | [% PROCESS tabrow name="tom" email="tom@here.org" %] |
126 | [% PROCESS tabrow name="dick" email="disk@there.org" %] |
127 | [% PROCESS tabrow name="larry" email="larry@where.org" %] |
128 | </table> |
129 | |
130 | =head1 Data and Code Binding |
131 | |
132 | One of the key features that sets the Template Toolkit apart from |
133 | other template processors is the ability to bind template variables to |
134 | any kind of Perl data: scalars, lists, hash arrays, sub-routines and |
135 | objects. |
136 | |
137 | my $vars = { |
138 | root => 'http://here.com/there', |
139 | menu => [ 'modules', 'authors', 'scripts' ], |
140 | client => { |
141 | name => 'Doctor Joseph von Satriani', |
142 | id => 'JVSAT', |
143 | }, |
144 | checkout => sub { my $total = shift; ...; return $something }, |
145 | shopcart => My::Cool::Shopping::Cart->new(), |
146 | }; |
147 | |
148 | The Template Toolkit will automatically Do The Right Thing to access the data |
149 | in an appropriate manner to return some value which can then be output. The |
150 | dot operator 'C<.>' is used to access into lists and hashes or to call object |
151 | methods. The C<FOREACH> directive is provided for iterating through lists, and |
152 | various logical tests are available using directives such as C<IF>, C<UNLESS>, |
153 | C<ELSIF>, C<ELSE>, C<SWITCH>, C<CASE>, etc. |
154 | |
155 | [% FOREACH section = menu %] |
156 | <a href="[% root %]/[% section %]/index.html">[% section %]</a> |
157 | [% END %] |
158 | |
159 | <b>Client</a>: [% client.name %] (id: [% client.id %]) |
160 | |
161 | [% IF shopcart.nitems %] |
162 | Your shopping cart contains the following items: |
163 | <ul> |
164 | [% FOREACH item = shopcart.contents %] |
165 | <li>[% item.name %] : [% item.qty %] @ [% item.price %] |
166 | [% END %] |
167 | </ul> |
168 | |
169 | [% checkout(shopcart.total) %] |
170 | |
171 | [% ELSE %] |
172 | No items currently in shopping cart. |
173 | [% END %] |
174 | |
175 | =head1 Advanced Features: Filters, Macros, Exceptions, Plugins |
176 | |
177 | The Template Toolkit also provides a number of additional directives |
178 | for advanced processing and programmatical functionality. It supports |
179 | output filters (FILTER), allows custom macros to be defined (MACRO), |
180 | has a fully-featured exception handling system (TRY, THROW, CATCH, |
181 | FINAL) and supports a plugin architecture (USE) which allows special |
182 | plugin modules and even regular Perl modules to be loaded and used |
183 | with the minimum of fuss. The Template Toolkit is "just" a template |
184 | processor but you can trivially extend it to incorporate the |
185 | functionality of any Perl module you can get your hands on. Thus, it |
186 | is also a scalable and extensible template framework, ideally suited |
187 | for managing the presentation layer for application servers, content |
188 | management systems and other web applications. |
189 | |
190 | =head1 Separating Presentation and Application Logic |
191 | |
192 | Rather than embedding Perl code or some other scripting language |
193 | directly into template documents, it encourages you to keep functional |
194 | components (i.e. Perl code) separate from presentation components |
195 | (e.g. HTML templates). The template variables provide the interface |
196 | between the two layers, allowing data to be generated in code and then |
197 | passed to a template component for displaying (pipeline model) or for |
198 | sub-routine or object references to be bound to variables which can |
199 | then be called from the template as and when required (callback |
200 | model). |
201 | |
202 | The directives that the Template Toolkit provide implement their own |
203 | mini programming language, but they're not really designed for |
204 | serious, general purpose programming. Perl is a far more appropriate |
205 | language for that. If you embed application logic (e.g. Perl or other |
206 | scripting language fragments) in HTML templates then you risk losing |
207 | the clear separation of concerns between functionality and |
208 | presentation. It becomes harder to maintain the two elements in |
209 | isolation and more difficult, if not impossible, to reuse code or |
210 | presentation elements by themselves. It is far better to write your |
211 | application code in separate Perl modules, libraries or scripts and |
212 | then use templates to control how the resulting data is presented as |
213 | output. Thus you should think of the Template Toolkit language as a |
214 | set of layout directives for displaying data, not calculating it. |
215 | |
216 | Having said that, the Template Toolkit doesn't force you into one |
217 | approach or the other. It attempts to be pragmatic rather than |
218 | dogmatic in allowing you to do whatever best gets the job done. |
219 | Thus, if you enable the EVAL_PERL option then you can happily embed |
220 | real Perl code in your templates within PERL ... END directives. |
221 | |
222 | =head1 Performance |
223 | |
224 | The Template Toolkit uses a fast YACC-like parser which compiles |
225 | templates into Perl code for maximum runtime efficiency. It also has |
226 | an advanced caching mechanism which manages in-memory and on-disk |
227 | (i.e. persistent) versions of compiled templates. The modules that |
228 | comprise the toolkit are highly configurable and the architecture |
229 | around which they're built is designed to be extensible. The Template |
230 | Toolkit provides a powerful framework around which content creation |
231 | and delivery systems can be built while also providing a simple |
232 | interface through the Template front-end module for general use. |
233 | |
234 | =cut |
235 | |
236 | # Local Variables: |
237 | # mode: perl |
238 | # perl-indent-level: 4 |
239 | # indent-tabs-mode: nil |
240 | # End: |
241 | # |
242 | # vim: expandtab shiftwidth=4: |