Project

General

Profile

TemplateParser » History » Version 31

Jan Klopper, 2012-04-10 15:21

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 16 Elmer de Looff
Something about tax indexing
229 16 Elmer de Looff
230 11 Elmer de Looff
h2. Tag functions
231 11 Elmer de Looff
232 15 Elmer de Looff
Tag functions
233 15 Elmer de Looff
234 21 Elmer de Looff
h3. Default html escaping
235 11 Elmer de Looff
236 11 Elmer de Looff
h3. Adding custom functions
237 11 Elmer de Looff
238 23 Elmer de Looff
h2. TemplateLoop
239 11 Elmer de Looff
240 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).
241 1 Elmer de Looff
242 23 Elmer de Looff
h3. Syntax and properties
243 23 Elmer de Looff
244 23 Elmer de Looff
*Syntax: @{{ for local_var in [collection] }}@*
245 20 Elmer de Looff
* The double accolades (curly braces) indicate the beginning and end of the construct;
246 20 Elmer de Looff
* The @for@ keyword indicates the structure to execute;
247 20 Elmer de Looff
* @local_var@ is the name which references the loop variable;
248 20 Elmer de Looff
* @[collection]@ is the tag that provides the iteratable.
249 20 Elmer de Looff
250 20 Elmer de Looff
*Properties*
251 20 Elmer de Looff
* The local name is stated without brackets (as it's no tag itself)
252 1 Elmer de Looff
* When it needs to be placed in the output, the local name should have brackets (like any other tag)
253 20 Elmer de Looff
* *N.B.* The local variable does _not_ bleed into the outer scope after the loop has completed.
254 20 Elmer de Looff
 It is therefore possible (though not recommended) to name the loop variable after the iterable: @{{ for collection in [collection] }}@.
255 20 Elmer de Looff
256 23 Elmer de Looff
h3. Example of a @TemplateLoop@
257 20 Elmer de Looff
258 20 Elmer de Looff
<pre><code class="html">
259 20 Elmer de Looff
<html>
260 20 Elmer de Looff
  <body>
261 20 Elmer de Looff
    <ul>
262 20 Elmer de Looff
    {{ for name in [presidents] }}
263 20 Elmer de Looff
      <li>President [name]</li>
264 20 Elmer de Looff
    {{ endfor }}
265 20 Elmer de Looff
    </ul>
266 20 Elmer de Looff
  </body>
267 20 Elmer de Looff
</html>
268 20 Elmer de Looff
</code></pre>
269 20 Elmer de Looff
270 20 Elmer de Looff
<pre><code class="python">
271 20 Elmer de Looff
>>> parser.Parse('rushmore.utp', presidents=['Washington', 'Jefferson', 'Roosevelt', 'Lincoln'])
272 20 Elmer de Looff
</code></pre>
273 20 Elmer de Looff
274 20 Elmer de Looff
<pre><code class="html">
275 20 Elmer de Looff
<html>
276 20 Elmer de Looff
  <body>
277 1 Elmer de Looff
    <ul>
278 1 Elmer de Looff
      <li>President Washington</li>
279 1 Elmer de Looff
      <li>President Jefferson</li>
280 1 Elmer de Looff
      <li>President Roosevelt</li>
281 1 Elmer de Looff
      <li>President Lincoln</li>
282 1 Elmer de Looff
    </ul>
283 1 Elmer de Looff
  </body>
284 1 Elmer de Looff
</html>
285 1 Elmer de Looff
</code></pre>
286 1 Elmer de Looff
287 1 Elmer de Looff
h2. Inlining templates
288 21 Elmer de Looff
289 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.
290 21 Elmer de Looff
291 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.
292 21 Elmer de Looff
293 21 Elmer de Looff
First, we will define our inline template, @'inline_hello.utp'@:
294 21 Elmer de Looff
295 21 Elmer de Looff
<pre><code class="html">
296 21 Elmer de Looff
<p>Hello [name]</p>
297 21 Elmer de Looff
</code></pre>
298 21 Elmer de Looff
299 21 Elmer de Looff
Secondly, our main template, @'hello.utp'@:
300 21 Elmer de Looff
301 21 Elmer de Looff
<pre><code class="html">
302 21 Elmer de Looff
<h1>Greetings</h1>
303 21 Elmer de Looff
{{ inline inline_hello.utp }}
304 21 Elmer de Looff
</code></pre>
305 21 Elmer de Looff
306 21 Elmer de Looff
Then we parse the template:
307 21 Elmer de Looff
308 21 Elmer de Looff
<pre><code class="python">
309 21 Elmer de Looff
>>> parser.Parse('hello.utp', name='Dr John')
310 21 Elmer de Looff
</code></pre>
311 21 Elmer de Looff
312 21 Elmer de Looff
<pre><code class="html">
313 21 Elmer de Looff
<h1>Greetings</h1>
314 21 Elmer de Looff
<p>Hello Dr John</p>
315 21 Elmer de Looff
</code></pre>
316 11 Elmer de Looff
317 11 Elmer de Looff
h2. Conditional statements
318 11 Elmer de Looff
319 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:
320 22 Elmer de Looff
321 22 Elmer de Looff
<pre><code class="html">
322 22 Elmer de Looff
<h1>Party attendees</h1>
323 22 Elmer de Looff
{{ if len([attendees]) > 1 }}
324 22 Elmer de Looff
  <ol>
325 22 Elmer de Looff
    {{ for attendee in [attendees] }}
326 22 Elmer de Looff
    <li>[attendee:name]</li>
327 22 Elmer de Looff
    {{ endfor }}
328 22 Elmer de Looff
  </ol>
329 22 Elmer de Looff
{{ elif [attendees] }}
330 22 Elmer de Looff
  <p>only [attendees:0:name] is attending.</p>
331 22 Elmer de Looff
{{ else }}
332 22 Elmer de Looff
  <p>There are no registered attendees yet.</p>
333 22 Elmer de Looff
{{ endif }}
334 22 Elmer de Looff
</code></pre>
335 22 Elmer de Looff
336 22 Elmer de Looff
For the case where there are several attendees:
337 22 Elmer de Looff
338 22 Elmer de Looff
<pre><code class="python">
339 22 Elmer de Looff
>>> parser.Parse('party.utp', attendees=[
340 22 Elmer de Looff
...    {'name': 'Livingstone'},
341 22 Elmer de Looff
...    {'name': 'Cook'},
342 22 Elmer de Looff
...    {'name': 'Drake'}])
343 22 Elmer de Looff
</code></pre>
344 22 Elmer de Looff
345 22 Elmer de Looff
<pre><code class="html">
346 22 Elmer de Looff
<h1>Party attendees</h1>
347 22 Elmer de Looff
<ol>
348 22 Elmer de Looff
  <li>Livingstone</li>
349 22 Elmer de Looff
  <li>Cook</li>
350 22 Elmer de Looff
  <li>Drake</li>
351 22 Elmer de Looff
</ol>
352 22 Elmer de Looff
</code></pre>
353 22 Elmer de Looff
354 22 Elmer de Looff
For the case where there is one attendee:
355 22 Elmer de Looff
356 22 Elmer de Looff
<pre><code class="python">
357 22 Elmer de Looff
>>> parser.Parse('party.utp', attendees=[{'name': 'Johnny'}])
358 22 Elmer de Looff
</code></pre>
359 22 Elmer de Looff
360 22 Elmer de Looff
<pre><code class="html">
361 22 Elmer de Looff
<h1>Party attendees</h1>
362 22 Elmer de Looff
<p>Only Johnny is attending.</p>
363 22 Elmer de Looff
</code></pre>
364 22 Elmer de Looff
365 22 Elmer de Looff
And in the case where there are no attendees:
366 22 Elmer de Looff
367 22 Elmer de Looff
<pre><code class="python">
368 22 Elmer de Looff
>>> parser.Parse('party.utp', attendees=[])
369 22 Elmer de Looff
</code></pre>
370 22 Elmer de Looff
371 22 Elmer de Looff
<pre><code class="html">
372 22 Elmer de Looff
<h1>Party attendees</h1>
373 22 Elmer de Looff
<p>There are no registered attendees yet.</p>
374 22 Elmer de Looff
</code></pre>
375 22 Elmer de Looff
376 22 Elmer de Looff
h3. Properties of conditional statements
377 22 Elmer de Looff
378 22 Elmer de Looff
* *All template keys must be referenced as proper tag*
379 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.
380 22 Elmer de Looff
* *It is possible to index tags in conditional statements*
381 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.
382 22 Elmer de Looff
* *Referencing a tag or index that doesn't exist raises @TemplateNameError*
383 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:
384 22 Elmer de Looff
* *Statement evaluation is lazy*
385 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.
386 22 Elmer de Looff
387 22 Elmer de Looff
388 11 Elmer de Looff
h2. Template unicode handling
389 11 Elmer de Looff
390 11 Elmer de Looff
Any @unicode@ object found while parsing, will automatically be encoded to UTF-8:
391 11 Elmer de Looff
392 11 Elmer de Looff
<pre><code class="python">
393 11 Elmer de Looff
>>> template = 'Underdark [love] [app]'
394 11 Elmer de Looff
>>> output = parser.ParseString(template, love=u'\u2665', app=u'\N{micro sign}Web')
395 11 Elmer de Looff
>>> output
396 12 Elmer de Looff
'Underdark \xe2\x99\xa5 \xc2\xb5Web'  # The output in its raw UTF-8 representation
397 11 Elmer de Looff
>>> output.decode('UTF8')
398 12 Elmer de Looff
u'Underdark \u2665 \xb5Web'           # The output converted to a Unicode object
399 19 Elmer de Looff
>>> print output
400 19 Elmer de Looff
Underdark ♥ µWeb                      # And the printed UTF-8 as we desired it.
401 14 Elmer de Looff
</code></pre>