Project

General

Profile

TemplateParser » History » Version 33

Elmer de Looff, 2012-04-16 11:50
header fixes

1 1 Elmer de Looff
h1. TemplateParser
2 25 Elmer de Looff
3 25 Elmer de Looff
{{>toc}}
4 1 Elmer de Looff
5 1 Elmer de Looff
The µWeb TemplateParser is a in-house developed templating engine that provides tag replacement, tag-functions and template control functions. This document will describe the following:
6 21 Elmer de Looff
* The *[[TemplateParser#template|Template class]]*, used to parse the templating language
7 21 Elmer de Looff
* The *[[TemplateParser#parser|Parser class]]*, which provides template loading and caching
8 21 Elmer de Looff
* *[[TemplateParser#using|Using TemplateParser]]* inside a µWeb PageMaker
9 21 Elmer de Looff
* *[[TemplateParser#syntax|Template syntax]]*, an overview of the language's constructs and behaviors
10 1 Elmer de Looff
11 1 Elmer de Looff
First though, to help with understanding the TemplateParser, a minimal size template document:
12 1 Elmer de Looff
13 1 Elmer de Looff
<pre><code class="html">
14 1 Elmer de Looff
Hello [title] [name]
15 1 Elmer de Looff
</code></pre>
16 4 Elmer de Looff
17 1 Elmer de Looff
The above document contains two simple template tags. These tags are delimited by square brackets, and they will be replaced by the named argument provided during parsing. If this name is not present, then the literal presentation of the tag will remain in the output.
18 1 Elmer de Looff
19 5 Elmer de Looff
h1(#template). Template class
20 4 Elmer de Looff
21 4 Elmer de Looff
The @Template@ class provides the interface for pre-parsing templates, loading them from files and parsing single templates to completion. During pre-parsing, constructs such as loops and conditional statements are converted to @TemplateLoop@ and @TemplateConditional@ objects, and their scopes nested appropriately in the @Template@. Tags are replaced by @TemplateTag@ instances, and text is captured in @TemplateText@. All of these provide @Parse@ methods, which together result in the combined parsed template output.
22 4 Elmer de Looff
23 4 Elmer de Looff
h2. Creating a template
24 4 Elmer de Looff
25 4 Elmer de Looff
A template is created simple by providing a string input to the @Template@'s constructor. This will return a valid Template instance (or raise an error if there is a problem with the [[TemplateParser#syntax|syntax]]:
26 4 Elmer de Looff
27 4 Elmer de Looff
<pre><code class="python">
28 21 Elmer de Looff
>>> import templateparser
29 4 Elmer de Looff
>>> template = templateparser.Template('Hello [title] [name]')
30 4 Elmer de Looff
>>> template
31 4 Elmer de Looff
Template([TemplateText('Hello '), TemplateTag('[title]'), TemplateText(' '), TemplateTag('[name]')])
32 4 Elmer de Looff
</code></pre>
33 4 Elmer de Looff
34 4 Elmer de Looff
Above can be seen the various parts of the template, which will be combined to output once parsed.
35 4 Elmer de Looff
36 4 Elmer de Looff
h2. Loading a template from file
37 4 Elmer de Looff
38 4 Elmer de Looff
The @Template@ class provides a @classmethod@ called @FromFile@, which loads the template at the path.
39 4 Elmer de Looff
40 4 Elmer de Looff
Loading a template named @example.utp@ from the current working directory:
41 4 Elmer de Looff
42 4 Elmer de Looff
<pre><code class="python">
43 21 Elmer de Looff
>>> import templateparser
44 4 Elmer de Looff
>>> template = templateparser.Template.FromFile('example.utp')
45 4 Elmer de Looff
>>> template
46 4 Elmer de Looff
Template([TemplateText('Hello '), TemplateTag('[title]'), TemplateText(' '), TemplateTag('[name]')])
47 4 Elmer de Looff
</code></pre>
48 4 Elmer de Looff
49 5 Elmer de Looff
h2. Parsing a template
50 4 Elmer de Looff
51 4 Elmer de Looff
Parsing a template can be done by calling the @Template@'s @Parse@ method. The keyword arguments provided to this call will from the replacement mapping for the template. In the following example, we will provide one such keyword, and leave the other undefined to show the (basic) behavior of the @Template.Parse@ method.
52 4 Elmer de Looff
53 4 Elmer de Looff
<pre><code class="python">
54 21 Elmer de Looff
>>> import templateparser
55 4 Elmer de Looff
>>> template = templateparser.Template('Hello [title] [name]')
56 8 Elmer de Looff
>>> template.Parse(title='sir')
57 8 Elmer de Looff
'Hello sir [name]'
58 4 Elmer de Looff
</code></pre>
59 1 Elmer de Looff
60 1 Elmer de Looff
h1(#parser). Parser class
61 6 Elmer de Looff
62 1 Elmer de Looff
The @Parser@ class provides simple management of multiple @Template@ objects. It is mainly used to load templates from disk. When initiating a @Parser@, the first argument provides the search path from where templates should be loaded (the default is the current working directory). An optional second argument can be provided to preload the template cache: a mapping of names and @Template@ objects.
63 1 Elmer de Looff
64 8 Elmer de Looff
h2. Loading templates
65 8 Elmer de Looff
66 6 Elmer de Looff
Creating a parser object, and loading the 'example.utp' template from the 'templates' directory works like this:
67 6 Elmer de Looff
68 6 Elmer de Looff
<pre><code class="python">
69 21 Elmer de Looff
>>> import templateparser
70 7 Elmer de Looff
>>> # This sets the 'templates' directory as the search path for AddTemplate
71 7 Elmer de Looff
>>> parser = templateparser.Parser('templates')
72 7 Elmer de Looff
>>> # Loads the 'templates/example.utp' and stores it as 'example.utp':
73 26 Elmer de Looff
>>> parser.AddTemplate('example.utp')
74 27 Elmer de Looff
>>> parser.Parse('example.utp', title='mister', name='Bob Dobalina')
75 1 Elmer de Looff
'Hello mister Bob Dobalina'
76 6 Elmer de Looff
</code></pre>
77 1 Elmer de Looff
78 29 Elmer de Looff
The @AddTemplate@ method takes a second optional argument, which allows us to give the template a different name in the cache:
79 29 Elmer de Looff
80 29 Elmer de Looff
<pre><code class="python">
81 29 Elmer de Looff
>>> parser = templateparser.Parser('templates')
82 30 Elmer de Looff
>>> parser.AddTemplate('example.utp', name='greeting')
83 29 Elmer de Looff
>>> parser.Parse('greeting', title='mister', name='Bob Dobalina')
84 29 Elmer de Looff
'Hello mister Bob Dobalina'
85 29 Elmer de Looff
</code></pre>
86 29 Elmer de Looff
87 29 Elmer de Looff
As you can see, the name of the template in the cache is not necessarily the same as the one on disk. Often though, this is not necessary to change, so @AddTemplate@ need only be called with one argument. Or not at all, as the following section will show.
88 1 Elmer de Looff
89 8 Elmer de Looff
h2. Template cache and auto-loading
90 8 Elmer de Looff
91 8 Elmer de Looff
The @Parser@ object behaves like a slightly modified dictionary to achieve this. Retrieving keys yields the associated template. Keys that are not present in the cache are _automatically_ retrieved from the filesystem:
92 8 Elmer de Looff
93 1 Elmer de Looff
<pre><code class="python">
94 21 Elmer de Looff
>>> import templateparser
95 7 Elmer de Looff
>>> parser = templateparser.Parser('templates')
96 28 Elmer de Looff
>>> 'example.utp' in parser
97 28 Elmer de Looff
False       # Since we haven't loaded it, the template it not in the parser
98 7 Elmer de Looff
>>> parser
99 1 Elmer de Looff
Parser({})  # The parser is empty (has no cached templates)
100 28 Elmer de Looff
</code></pre>
101 28 Elmer de Looff
102 28 Elmer de Looff
Attempting to parse a template that doesn't exist in the parser cache triggers an automatic load:
103 28 Elmer de Looff
104 28 Elmer de Looff
<pre><code class="python">
105 1 Elmer de Looff
>>> parser['example.utp'].Parse(title='mister', name='Bob Dobalina')
106 1 Elmer de Looff
'Hello mister Bob Dobalina'
107 28 Elmer de Looff
>>> 'example.utp' in parser
108 28 Elmer de Looff
True
109 1 Elmer de Looff
>>> parser
110 8 Elmer de Looff
Parser({'example.utp': Template([TemplateText('Hello '), TemplateTag('[title]'),
111 8 Elmer de Looff
                                 TemplateText(' '), TemplateTag('[name]')])})
112 7 Elmer de Looff
</code></pre>
113 7 Elmer de Looff
114 7 Elmer de Looff
If these cannot be found, @TemplateReadError@ is raised:
115 7 Elmer de Looff
116 7 Elmer de Looff
<pre><code class="python">
117 21 Elmer de Looff
>>> import templateparser
118 7 Elmer de Looff
>>> parser = templateparser.Parser('templates')
119 6 Elmer de Looff
>>> parser['bad_template.utp'].Parse(failure='imminent')
120 6 Elmer de Looff
Traceback (most recent call last):
121 6 Elmer de Looff
  File "<stdin>", line 1, in <module>
122 7 Elmer de Looff
  File "/var/lib/underdark/libs/uweb/templateparser.py", line 147, in __getitem__
123 6 Elmer de Looff
    self.AddTemplate(template)
124 1 Elmer de Looff
  File "/var/lib/underdark/libs/uweb/templateparser.py", line 171, in AddTemplate
125 1 Elmer de Looff
    raise TemplateReadError('Could not load template %r' % template_path)
126 1 Elmer de Looff
underdark.libs.uweb.templateparser.TemplateReadError: Could not load template 'templates/bad_template.utp'
127 1 Elmer de Looff
</code></pre>
128 8 Elmer de Looff
129 18 Elmer de Looff
h2. @Parse@ and @ParseString@ methods
130 8 Elmer de Looff
131 8 Elmer de Looff
For convencience and consistency, the @Parser@ comes with two handy methods to provide parsing of @Template@ objects, one from its cache, one from raw template strings. It is recommended to use these over the previously shown direct key-based access:
132 8 Elmer de Looff
133 8 Elmer de Looff
<pre><code class="python">
134 21 Elmer de Looff
>>> import templateparser
135 8 Elmer de Looff
>>> parser = templateparser.Parser('templates')
136 8 Elmer de Looff
>>> parser.Parse('example.utp', title='mister', name='Bob Dobalina')
137 8 Elmer de Looff
'Hello mister Bob Dobalina'
138 8 Elmer de Looff
>>> parser.ParseString('Hello [title] [name]', title='mister', name='Bob Dobalina')
139 8 Elmer de Looff
'Hello mister Bob Dobalina'</code></pre>
140 6 Elmer de Looff
141 1 Elmer de Looff
h1(#using). Using TemplateParser inside µWeb
142 10 Elmer de Looff
143 10 Elmer de Looff
Within the default µWeb @PageMaker@, there is a @parser@ property, which provides a [[TemplateParser#parser|Parser]] object. The class constant @TEMPLATE_DIR@ provides the template search directory. The default template directory is @'templates'@. *N.B.* This path is relative to the file that contains the PageMaker class.
144 10 Elmer de Looff
145 10 Elmer de Looff
An example of TemplateParser to create a complete response:
146 10 Elmer de Looff
<pre><code class="python">
147 31 Jan Klopper
import uweb
148 10 Elmer de Looff
import time
149 10 Elmer de Looff
150 10 Elmer de Looff
class PageMaker(uweb.PageMaker):
151 10 Elmer de Looff
  def VersionPage(self):
152 10 Elmer de Looff
    return self.parser.Parse(
153 10 Elmer de Looff
      'version.utp', year=time.strftime('%Y'), version=uweb.__version__)
154 10 Elmer de Looff
</code></pre>
155 10 Elmer de Looff
156 10 Elmer de Looff
The example template for the above file could look something like this:
157 10 Elmer de Looff
158 10 Elmer de Looff
159 10 Elmer de Looff
<pre><code class="html">
160 10 Elmer de Looff
<!DOCTYPE html>
161 10 Elmer de Looff
<html>
162 10 Elmer de Looff
  <head>
163 10 Elmer de Looff
    <title>µWeb version info</title>
164 10 Elmer de Looff
  </head>
165 10 Elmer de Looff
  <body>
166 10 Elmer de Looff
    <p>µWeb version [version] - Copyright 2010-[year] Underdark</p>
167 10 Elmer de Looff
  </body>
168 10 Elmer de Looff
</html>
169 10 Elmer de Looff
</code></pre>
170 1 Elmer de Looff
171 5 Elmer de Looff
h1(#syntax). Templating language syntax
172 11 Elmer de Looff
173 11 Elmer de Looff
The templating syntax is relatively limited, but with the limited syntax it provides a flexible and rich system to create templates. Covered in these examples are:
174 11 Elmer de Looff
* Simple tags (used in various examples above)
175 11 Elmer de Looff
* Tag indexing
176 11 Elmer de Looff
* Tag functions
177 11 Elmer de Looff
* Template language constructs
178 11 Elmer de Looff
179 11 Elmer de Looff
All examples will consist of three parts:
180 11 Elmer de Looff
# The example template
181 11 Elmer de Looff
# The python invocation string (the template will be named 'example.utp')
182 11 Elmer de Looff
# The resulting output (as source, not as parsed HTML)
183 11 Elmer de Looff
184 11 Elmer de Looff
h2. Simple tags
185 11 Elmer de Looff
186 11 Elmer de Looff
This is an example for the most basic form of template tags. The tag is enclosed by square brackets as such: @[tag]@. Tags that match a provided argument to the Parse call get replaced. If there is no argument that matches the tag name, it is returned in the output verbatim. This is also demonstrated in the below example
187 11 Elmer de Looff
188 11 Elmer de Looff
The example below is a repeat of the example how to use TemplateParser inside µWeb, and shows the template result:
189 11 Elmer de Looff
190 11 Elmer de Looff
<pre><code class="html">
191 11 Elmer de Looff
<!DOCTYPE html>
192 11 Elmer de Looff
<html>
193 11 Elmer de Looff
  <head>
194 11 Elmer de Looff
    <title>µWeb version info</title>
195 11 Elmer de Looff
  </head>
196 11 Elmer de Looff
  <body>
197 11 Elmer de Looff
    <p>µWeb version [version] - Copyright 2010-[year] Underdark</p>
198 11 Elmer de Looff
    <p>
199 11 Elmer de Looff
      This [paragraph] is not replaced because there is no
200 11 Elmer de Looff
      paragraph argument provided to the parser.
201 11 Elmer de Looff
    </p>
202 11 Elmer de Looff
  </body>
203 11 Elmer de Looff
</html>
204 11 Elmer de Looff
</code></pre>
205 11 Elmer de Looff
206 11 Elmer de Looff
<pre><code class="python">
207 11 Elmer de Looff
>>> parser.Parse('version.utp', year=time.strftime('%Y'), version=uweb.__version__)
208 11 Elmer de Looff
</code></pre>
209 11 Elmer de Looff
210 11 Elmer de Looff
<pre><code class="html">
211 11 Elmer de Looff
<!DOCTYPE html>
212 11 Elmer de Looff
<html>
213 11 Elmer de Looff
  <head>
214 11 Elmer de Looff
    <title>µWeb version info</title>
215 11 Elmer de Looff
  </head>
216 11 Elmer de Looff
  <body>
217 11 Elmer de Looff
    <p>µWeb version 0.11 - Copyright 2010-212 Underdark</p>
218 11 Elmer de Looff
    <p>
219 11 Elmer de Looff
      This [paragraph] is not replaced because there is no
220 11 Elmer de Looff
      paragraph argument provided to the parser.
221 11 Elmer de Looff
    </p>
222 11 Elmer de Looff
  </body>
223 11 Elmer de Looff
</html>
224 11 Elmer de Looff
</code></pre>
225 11 Elmer de Looff
226 11 Elmer de Looff
h2. Tag indexing
227 11 Elmer de Looff
228 32 Elmer de Looff
In addition to simple (re)placement of strings using the @TemplateParser@, you can also provide it with a @list@, @dictionary@, or other indexable object, and from it, fetch various @indices@, @keys@ or @attributes@. The separation character between the _tagname_ and the _index_ is the _colon_ (":"):
229 32 Elmer de Looff
230 32 Elmer de Looff
231 32 Elmer de Looff
h3. List/tuple index addressing
232 32 Elmer de Looff
233 32 Elmer de Looff
<pre><code class="html">
234 32 Elmer de Looff
This is [var:0] [var:1].
235 32 Elmer de Looff
</code></pre>
236 32 Elmer de Looff
237 32 Elmer de Looff
<pre><code class="python">
238 32 Elmer de Looff
>>> parser.Parse('message.utp', var=('delicious', 'spam'))
239 32 Elmer de Looff
</code></pre>
240 32 Elmer de Looff
241 32 Elmer de Looff
<pre><code class="html">
242 32 Elmer de Looff
This is delicious spam.
243 32 Elmer de Looff
</code></pre>
244 32 Elmer de Looff
245 33 Elmer de Looff
h3. Dictionary key addressing
246 32 Elmer de Looff
247 32 Elmer de Looff
<pre><code class="html">
248 32 Elmer de Looff
This is [var:adjective] [var:noun].
249 32 Elmer de Looff
</code></pre>
250 32 Elmer de Looff
251 32 Elmer de Looff
<pre><code class="python">
252 32 Elmer de Looff
>>> parser.Parse('message.utp', var={'adjective': 'delicious', 'noun': 'spam'})
253 32 Elmer de Looff
</code></pre>
254 32 Elmer de Looff
255 32 Elmer de Looff
<pre><code class="html">
256 32 Elmer de Looff
This is delicious spam.
257 32 Elmer de Looff
</code></pre>
258 32 Elmer de Looff
259 33 Elmer de Looff
h3. Attribute name addressing
260 32 Elmer de Looff
261 32 Elmer de Looff
<pre><code class="html">
262 32 Elmer de Looff
This is [var:adjective] [var:noun].
263 32 Elmer de Looff
</code></pre>
264 32 Elmer de Looff
265 32 Elmer de Looff
<pre><code class="python">
266 32 Elmer de Looff
>>> class Struct(object):
267 32 Elmer de Looff
...   pass
268 32 Elmer de Looff
...
269 32 Elmer de Looff
>>> var = Struct()
270 32 Elmer de Looff
>>> var.adjective = 'delicious'
271 32 Elmer de Looff
>>> var.noun = 'spam'
272 32 Elmer de Looff
>>> parser.Parse('message.utp', var=var)
273 32 Elmer de Looff
</code></pre>
274 32 Elmer de Looff
275 32 Elmer de Looff
<pre><code class="html">
276 32 Elmer de Looff
This is delicious spam.
277 32 Elmer de Looff
</code></pre>
278 32 Elmer de Looff
279 33 Elmer de Looff
h3. Lookup order
280 32 Elmer de Looff
281 32 Elmer de Looff
For objects and constructs that provide multiple ways of looking up information, the lookup order can be very important. For any of the first three steps, if they are successful, the retrieved value is returned, and no further attempts are made:
282 32 Elmer de Looff
283 32 Elmer de Looff
# If the @needle@ is parseable as integer, it will first be used as an index. This will also work for mappings with numeric keys;
284 32 Elmer de Looff
# If the above fails, the @needle@ is assumed to be a string-like mapping key, and this is attempted
285 32 Elmer de Looff
# If the above fails, the @needle@ is used as an attribute name;
286 32 Elmer de Looff
# If all of the above fail, *@TemplateKeyError@* is raised, as the @needle@ could not be found on the object.
287 16 Elmer de Looff
288 11 Elmer de Looff
h2. Tag functions
289 11 Elmer de Looff
290 15 Elmer de Looff
Tag functions
291 15 Elmer de Looff
292 21 Elmer de Looff
h3. Default html escaping
293 11 Elmer de Looff
294 11 Elmer de Looff
h3. Adding custom functions
295 11 Elmer de Looff
296 23 Elmer de Looff
h2. TemplateLoop
297 11 Elmer de Looff
298 23 Elmer de Looff
As a language construct, TemplateParser has an understanding of iteration. The @TemplateLoop@ can be compared to the Python @for@-loop, or the @foreach@ construct in other languages (lazy iteration over the values of an iterable).
299 1 Elmer de Looff
300 23 Elmer de Looff
h3. Syntax and properties
301 23 Elmer de Looff
302 23 Elmer de Looff
*Syntax: @{{ for local_var in [collection] }}@*
303 20 Elmer de Looff
* The double accolades (curly braces) indicate the beginning and end of the construct;
304 20 Elmer de Looff
* The @for@ keyword indicates the structure to execute;
305 20 Elmer de Looff
* @local_var@ is the name which references the loop variable;
306 20 Elmer de Looff
* @[collection]@ is the tag that provides the iteratable.
307 20 Elmer de Looff
308 20 Elmer de Looff
*Properties*
309 20 Elmer de Looff
* The local name is stated without brackets (as it's no tag itself)
310 1 Elmer de Looff
* When it needs to be placed in the output, the local name should have brackets (like any other tag)
311 20 Elmer de Looff
* *N.B.* The local variable does _not_ bleed into the outer scope after the loop has completed.
312 20 Elmer de Looff
 It is therefore possible (though not recommended) to name the loop variable after the iterable: @{{ for collection in [collection] }}@.
313 20 Elmer de Looff
314 23 Elmer de Looff
h3. Example of a @TemplateLoop@
315 20 Elmer de Looff
316 20 Elmer de Looff
<pre><code class="html">
317 20 Elmer de Looff
<html>
318 20 Elmer de Looff
  <body>
319 20 Elmer de Looff
    <ul>
320 20 Elmer de Looff
    {{ for name in [presidents] }}
321 20 Elmer de Looff
      <li>President [name]</li>
322 20 Elmer de Looff
    {{ endfor }}
323 20 Elmer de Looff
    </ul>
324 20 Elmer de Looff
  </body>
325 20 Elmer de Looff
</html>
326 20 Elmer de Looff
</code></pre>
327 20 Elmer de Looff
328 20 Elmer de Looff
<pre><code class="python">
329 20 Elmer de Looff
>>> parser.Parse('rushmore.utp', presidents=['Washington', 'Jefferson', 'Roosevelt', 'Lincoln'])
330 20 Elmer de Looff
</code></pre>
331 20 Elmer de Looff
332 20 Elmer de Looff
<pre><code class="html">
333 20 Elmer de Looff
<html>
334 20 Elmer de Looff
  <body>
335 1 Elmer de Looff
    <ul>
336 1 Elmer de Looff
      <li>President Washington</li>
337 1 Elmer de Looff
      <li>President Jefferson</li>
338 1 Elmer de Looff
      <li>President Roosevelt</li>
339 1 Elmer de Looff
      <li>President Lincoln</li>
340 1 Elmer de Looff
    </ul>
341 1 Elmer de Looff
  </body>
342 1 Elmer de Looff
</html>
343 1 Elmer de Looff
</code></pre>
344 1 Elmer de Looff
345 1 Elmer de Looff
h2. Inlining templates
346 21 Elmer de Looff
347 21 Elmer de Looff
Often, there will be snippets of a template that will see a lot of reuse. Page headers and footers are often the same on many pages, and having several redundant copies means that changes will have to be replicated to each of these occurrances. To reduce the need for this, TemplateParser has an @inline@ statement. Using this you can specify a template that is available in the @[[TemplateParser#Parser]]@ instance and the statement will be replaced by the template.
348 21 Elmer de Looff
349 21 Elmer de Looff
Of course, if the inlined template is not already in the @Parser@ instance, the autoloading mechanism will trigger, and the named template will be search for in the @Parser@'s template directory.
350 21 Elmer de Looff
351 21 Elmer de Looff
First, we will define our inline template, @'inline_hello.utp'@:
352 21 Elmer de Looff
353 21 Elmer de Looff
<pre><code class="html">
354 21 Elmer de Looff
<p>Hello [name]</p>
355 21 Elmer de Looff
</code></pre>
356 21 Elmer de Looff
357 21 Elmer de Looff
Secondly, our main template, @'hello.utp'@:
358 21 Elmer de Looff
359 21 Elmer de Looff
<pre><code class="html">
360 21 Elmer de Looff
<h1>Greetings</h1>
361 21 Elmer de Looff
{{ inline inline_hello.utp }}
362 21 Elmer de Looff
</code></pre>
363 21 Elmer de Looff
364 21 Elmer de Looff
Then we parse the template:
365 21 Elmer de Looff
366 21 Elmer de Looff
<pre><code class="python">
367 21 Elmer de Looff
>>> parser.Parse('hello.utp', name='Dr John')
368 21 Elmer de Looff
</code></pre>
369 21 Elmer de Looff
370 21 Elmer de Looff
<pre><code class="html">
371 21 Elmer de Looff
<h1>Greetings</h1>
372 21 Elmer de Looff
<p>Hello Dr John</p>
373 21 Elmer de Looff
</code></pre>
374 11 Elmer de Looff
375 11 Elmer de Looff
h2. Conditional statements
376 11 Elmer de Looff
377 22 Elmer de Looff
Often, you'll want the output of your template to be dependent on the value, presence, or boolean value of another tag. For instance, we may want a print a list of attendees to a party. We start the @if@ conditional by checking the boolean value of the @attendees@ tag. If this list if not-empty, we will print the attendee names, but if it's empty (or contains only a single entry), we'll tell the user in more intelligent ways than giving them a list with zero entries:
378 22 Elmer de Looff
379 22 Elmer de Looff
<pre><code class="html">
380 22 Elmer de Looff
<h1>Party attendees</h1>
381 22 Elmer de Looff
{{ if len([attendees]) > 1 }}
382 22 Elmer de Looff
  <ol>
383 22 Elmer de Looff
    {{ for attendee in [attendees] }}
384 22 Elmer de Looff
    <li>[attendee:name]</li>
385 22 Elmer de Looff
    {{ endfor }}
386 22 Elmer de Looff
  </ol>
387 22 Elmer de Looff
{{ elif [attendees] }}
388 22 Elmer de Looff
  <p>only [attendees:0:name] is attending.</p>
389 22 Elmer de Looff
{{ else }}
390 22 Elmer de Looff
  <p>There are no registered attendees yet.</p>
391 22 Elmer de Looff
{{ endif }}
392 22 Elmer de Looff
</code></pre>
393 22 Elmer de Looff
394 22 Elmer de Looff
For the case where there are several attendees:
395 22 Elmer de Looff
396 22 Elmer de Looff
<pre><code class="python">
397 22 Elmer de Looff
>>> parser.Parse('party.utp', attendees=[
398 22 Elmer de Looff
...    {'name': 'Livingstone'},
399 22 Elmer de Looff
...    {'name': 'Cook'},
400 22 Elmer de Looff
...    {'name': 'Drake'}])
401 22 Elmer de Looff
</code></pre>
402 22 Elmer de Looff
403 22 Elmer de Looff
<pre><code class="html">
404 22 Elmer de Looff
<h1>Party attendees</h1>
405 22 Elmer de Looff
<ol>
406 22 Elmer de Looff
  <li>Livingstone</li>
407 22 Elmer de Looff
  <li>Cook</li>
408 22 Elmer de Looff
  <li>Drake</li>
409 22 Elmer de Looff
</ol>
410 22 Elmer de Looff
</code></pre>
411 22 Elmer de Looff
412 22 Elmer de Looff
For the case where there is one attendee:
413 22 Elmer de Looff
414 22 Elmer de Looff
<pre><code class="python">
415 22 Elmer de Looff
>>> parser.Parse('party.utp', attendees=[{'name': 'Johnny'}])
416 22 Elmer de Looff
</code></pre>
417 22 Elmer de Looff
418 22 Elmer de Looff
<pre><code class="html">
419 22 Elmer de Looff
<h1>Party attendees</h1>
420 22 Elmer de Looff
<p>Only Johnny is attending.</p>
421 22 Elmer de Looff
</code></pre>
422 22 Elmer de Looff
423 22 Elmer de Looff
And in the case where there are no attendees:
424 22 Elmer de Looff
425 22 Elmer de Looff
<pre><code class="python">
426 22 Elmer de Looff
>>> parser.Parse('party.utp', attendees=[])
427 22 Elmer de Looff
</code></pre>
428 22 Elmer de Looff
429 22 Elmer de Looff
<pre><code class="html">
430 22 Elmer de Looff
<h1>Party attendees</h1>
431 22 Elmer de Looff
<p>There are no registered attendees yet.</p>
432 22 Elmer de Looff
</code></pre>
433 22 Elmer de Looff
434 22 Elmer de Looff
h3. Properties of conditional statements
435 22 Elmer de Looff
436 22 Elmer de Looff
* *All template keys must be referenced as proper tag*
437 22 Elmer de Looff
 This is to prevent mixing of the template variables with the functions and reserved names of Python itself. Conditional expressions are evaluated using @eval()@, and proper tags are replaced by temporary names, the values of which are stored in a retrieve-on-demand dictionary. This makes them perfectly safe with regard to the value of template replacements, but some care should be taken with the writing of the conditional expressions.
438 22 Elmer de Looff
* *It is possible to index tags in conditional statements*
439 22 Elmer de Looff
 This allows for decisions based on the values in those indexes/keys. For instance, @Person@ objects can be checked for gender, so that the correct gender-based icon can be displayed next to them.
440 22 Elmer de Looff
* *Referencing a tag or index that doesn't exist raises @TemplateNameError*
441 22 Elmer de Looff
 Unlike in regular template text, there is no suitable fallback value for a tag or index that cannot be retrieved. However, in most cases this can be prevented by making use of the following property:
442 22 Elmer de Looff
* *Statement evaluation is lazy*
443 22 Elmer de Looff
 Template conditions are processed left to right, and short-circuited where possible. If the first member of an @or@ group succeeds, the return value is already known. Similarly, if the first member of an @and@ group fails, the second part need not be evaluated. This way @TemplateNameErrors@ can often be prevented, as in most cases, presence of indexes can be confirmed before accessing.
444 22 Elmer de Looff
445 22 Elmer de Looff
446 11 Elmer de Looff
h2. Template unicode handling
447 11 Elmer de Looff
448 11 Elmer de Looff
Any @unicode@ object found while parsing, will automatically be encoded to UTF-8:
449 11 Elmer de Looff
450 11 Elmer de Looff
<pre><code class="python">
451 11 Elmer de Looff
>>> template = 'Underdark [love] [app]'
452 11 Elmer de Looff
>>> output = parser.ParseString(template, love=u'\u2665', app=u'\N{micro sign}Web')
453 11 Elmer de Looff
>>> output
454 12 Elmer de Looff
'Underdark \xe2\x99\xa5 \xc2\xb5Web'  # The output in its raw UTF-8 representation
455 11 Elmer de Looff
>>> output.decode('UTF8')
456 12 Elmer de Looff
u'Underdark \u2665 \xb5Web'           # The output converted to a Unicode object
457 19 Elmer de Looff
>>> print output
458 19 Elmer de Looff
Underdark ♥ µWeb                      # And the printed UTF-8 as we desired it.
459 14 Elmer de Looff
</code></pre>