Mercurial > genshi > mirror
annotate doc/templates.txt @ 820:9755836bb396 experimental-inline
Sync (old) experimental inline branch with trunk@1027.
author | cmlenz |
---|---|
date | Wed, 11 Mar 2009 17:51:06 +0000 |
parents | 3eb30e4ece8c |
children | fe25855324dd |
rev | line source |
---|---|
500 | 1 .. -*- mode: rst; encoding: utf-8 -*- |
2 | |
3 ======================== | |
4 Genshi Templating Basics | |
5 ======================== | |
6 | |
7 Genshi provides a template engine that can be used for generating either | |
8 markup (such as HTML_ or XML_) or plain text. While both share some of the | |
9 syntax (and much of the underlying implementation) they are essentially | |
10 separate languages. | |
11 | |
12 .. _html: http://www.w3.org/html/ | |
13 .. _xml: http://www.w3.org/XML/ | |
14 | |
15 This document describes the common parts of the template engine and will be most | |
16 useful as reference to those developing Genshi templates. Templates are XML or | |
17 plain text files that include processing directives_ that affect how the | |
18 template is rendered, and template expressions_ that are dynamically substituted | |
19 by variable data. | |
20 | |
21 | |
22 .. contents:: Contents | |
23 :depth: 3 | |
24 .. sectnum:: | |
25 | |
26 -------- | |
27 Synopsis | |
28 -------- | |
29 | |
30 A Genshi *markup template* is a well-formed XML document with embedded Python | |
31 used for control flow and variable substitution. Markup templates should be | |
32 used to generate any kind of HTML or XML output, as they provide many advantages | |
33 over simple text-based templates (such as automatic escaping of strings). | |
34 | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
35 The following illustrates a very basic Genshi markup template: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
36 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
37 .. code-block:: genshi |
500 | 38 |
39 <?python | |
40 title = "A Genshi Template" | |
41 fruits = ["apple", "orange", "kiwi"] | |
42 ?> | |
43 <html xmlns:py="http://genshi.edgewall.org/"> | |
44 <head> | |
45 <title py:content="title">This is replaced.</title> | |
46 </head> | |
47 | |
48 <body> | |
49 <p>These are some of my favorite fruits:</p> | |
50 <ul> | |
51 <li py:for="fruit in fruits"> | |
52 I like ${fruit}s | |
53 </li> | |
54 </ul> | |
55 </body> | |
56 </html> | |
57 | |
58 This example shows: | |
59 | |
60 (a) a Python code block, using a processing instruction | |
61 (b) the Genshi namespace declaration | |
62 (c) usage of templates directives (``py:content`` and ``py:for``) | |
63 (d) an inline Python expression (``${fruit}``). | |
64 | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
65 The template would generate output similar to this: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
66 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
67 .. code-block:: genshi |
500 | 68 |
69 <html> | |
70 <head> | |
71 <title>A Genshi Template</title> | |
72 </head> | |
73 | |
74 <body> | |
75 <p>These are some of my favorite fruits:</p> | |
76 <ul> | |
77 <li>I like apples</li> | |
78 <li>I like oranges</li> | |
79 <li>I like kiwis</li> | |
80 </ul> | |
81 </body> | |
82 </html> | |
83 | |
84 A *text template* is a simple plain text document that can also contain embedded | |
85 Python code. Text templates can be used to generate simple *non-markup* text | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
86 formats, such as the body of an plain text email. For example: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
87 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
88 .. code-block:: genshitext |
500 | 89 |
90 Dear $name, | |
91 | |
92 These are some of my favorite fruits: | |
93 #for fruit in fruits | |
94 * $fruit | |
95 #end | |
96 | |
97 | |
98 ---------- | |
99 Python API | |
100 ---------- | |
101 | |
102 The Python code required for templating with Genshi is generally based on the | |
103 following pattern: | |
104 | |
105 * Attain a ``MarkupTemplate`` or ``TextTemplate`` object from a string or | |
106 file-like object containing the template source. This can either be done | |
107 directly, or through a ``TemplateLoader`` instance. | |
108 * Call the ``generate()`` method of the template, passing any data that should | |
109 be made available to the template as keyword arguments. | |
110 * Serialize the resulting stream using its ``render()`` method. | |
111 | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
112 For example: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
113 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
114 .. code-block:: pycon |
500 | 115 |
116 >>> from genshi.template import MarkupTemplate | |
117 >>> tmpl = MarkupTemplate('<h1>Hello, $name!</h1>') | |
118 >>> stream = tmpl.generate(name='world') | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
119 >>> print stream.render('xhtml') |
500 | 120 <h1>Hello, world!</h1> |
121 | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
122 .. note:: See the Serialization_ section of the `Markup Streams`_ page for |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
123 information on configuring template output options. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
124 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
125 Using a text template is similar: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
126 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
127 .. code-block:: pycon |
500 | 128 |
129 >>> from genshi.template import TextTemplate | |
130 >>> tmpl = TextTemplate('Hello, $name!') | |
131 >>> stream = tmpl.generate(name='world') | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
132 >>> print stream |
500 | 133 Hello, world! |
134 | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
135 .. note:: If you want to use text templates, you should consider using the |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
136 ``NewTextTemplate`` class instead of simply ``TextTemplate``. See |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
137 the `Text Template Language`_ page. |
500 | 138 |
139 .. _serialization: streams.html#serialization | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
140 .. _`Text Template Language`: text-templates.html |
500 | 141 .. _`Markup Streams`: streams.html |
142 | |
143 Using a template loader provides the advantage that “compiled” templates are | |
144 automatically cached, and only parsed again when the template file changes. In | |
145 addition, it enables the use of a *template search path*, allowing template | |
146 directories to be spread across different file-system locations. Using a | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
147 template loader would generally look as follows: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
148 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
149 .. code-block:: python |
500 | 150 |
151 from genshi.template import TemplateLoader | |
152 loader = TemplateLoader([templates_dir1, templates_dir2]) | |
153 tmpl = loader.load('test.html') | |
154 stream = tmpl.generate(title='Hello, world!') | |
155 print stream.render() | |
156 | |
157 See the `API documentation <api/index.html>`_ for details on using Genshi via | |
158 the Python API. | |
159 | |
160 | |
161 .. _`expressions`: | |
162 | |
163 ------------------------------------ | |
164 Template Expressions and Code Blocks | |
165 ------------------------------------ | |
166 | |
167 Python_ expressions can be used in text and directive arguments. An expression | |
168 is substituted with the result of its evaluation against the template data. | |
169 Expressions in text (which includes the values of non-directive attributes) need | |
170 to prefixed with a dollar sign (``$``) and usually enclosed in curly braces | |
171 (``{…}``). | |
172 | |
173 .. _python: http://www.python.org/ | |
174 | |
175 If the expression starts with a letter and contains only letters, digits, dots, | |
176 and underscores, the curly braces may be omitted. In all other cases, the | |
177 braces are required so that the template processor knows where the expression | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
178 ends: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
179 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
180 .. code-block:: pycon |
500 | 181 |
182 >>> from genshi.template import MarkupTemplate | |
183 >>> tmpl = MarkupTemplate('<em>${items[0].capitalize()} item</em>') | |
184 >>> print tmpl.generate(items=['first', 'second']) | |
185 <em>First item</em> | |
186 | |
187 Expressions support the full power of Python. In addition, it is possible to | |
188 access items in a dictionary using “dotted notation” (i.e. as if they were | |
189 attributes), and vice-versa (i.e. access attributes as if they were items in a | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
190 dictionary): |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
191 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
192 .. code-block:: pycon |
500 | 193 |
194 >>> from genshi.template import MarkupTemplate | |
195 >>> tmpl = MarkupTemplate('<em>${dict.foo}</em>') | |
196 >>> print tmpl.generate(dict={'foo': 'bar'}) | |
197 <em>bar</em> | |
198 | |
199 Because there are two ways to access either attributes or items, expressions | |
200 do not raise the standard ``AttributeError`` or ``IndexError`` exceptions, but | |
201 rather an exception of the type ``UndefinedError``. The same kind of error is | |
202 raised when you try to use a top-level variable that is not in the context data. | |
203 See `Error Handling`_ below for details on how such errors are handled. | |
204 | |
205 | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
206 Escaping |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
207 ======== |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
208 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
209 If you need to include a literal dollar sign in the output where Genshi would |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
210 normally detect an expression, you can simply add another dollar sign: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
211 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
212 .. code-block:: pycon |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
213 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
214 >>> from genshi.template import MarkupTemplate |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
215 >>> tmpl = MarkupTemplate('<em>$foo</em>') # Wanted "$foo" as literal output |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
216 >>> print tmpl.generate() |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
217 Traceback (most recent call last): |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
218 ... |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
219 UndefinedError: "foo" not defined |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
220 >>> tmpl = MarkupTemplate('<em>$$foo</em>') |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
221 >>> print tmpl.generate() |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
222 <em>$foo</em> |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
223 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
224 But note that this is not necessary if the characters following the dollar sign |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
225 do not qualify as an expression. For example, the following needs no escaping: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
226 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
227 .. code-block:: pycon |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
228 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
229 >>> tmpl = MarkupTemplate('<script>$(function() {})</script>') |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
230 >>> print tmpl.generate() |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
231 <script>$(function() {})</script> |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
232 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
233 On the other hand, Genshi will always replace two dollar signs in text with a |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
234 single dollar sign, so you'll need to use three dollar signs to get two in the |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
235 output: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
236 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
237 .. code-block:: pycon |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
238 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
239 >>> tmpl = MarkupTemplate('<script>$$$("div")</script>') |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
240 >>> print tmpl.generate() |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
241 <script>$$("div")</script> |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
242 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
243 |
500 | 244 .. _`code blocks`: |
245 | |
246 Code Blocks | |
247 =========== | |
248 | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
249 Templates also support full Python code blocks, using the ``<?python ?>`` |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
250 processing instruction in XML templates: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
251 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
252 .. code-block:: genshi |
500 | 253 |
254 <div> | |
255 <?python | |
256 from genshi.builder import tag | |
257 def greeting(name): | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
258 return tag.b('Hello, %s!' % name) ?> |
500 | 259 ${greeting('world')} |
260 </div> | |
261 | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
262 This will produce the following output: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
263 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
264 .. code-block:: xml |
500 | 265 |
266 <div> | |
267 <b>Hello, world!</b> | |
268 </div> | |
269 | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
270 In text templates (although only those using the new syntax introduced in |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
271 Genshi 0.5), code blocks use the special ``{% python %}`` directive: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
272 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
273 .. code-block:: genshitext |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
274 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
275 {% python |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
276 from genshi.builder import tag |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
277 def greeting(name): |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
278 return 'Hello, %s!' % name |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
279 %} |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
280 ${greeting('world')} |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
281 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
282 This will produce the following output:: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
283 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
284 Hello, world! |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
285 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
286 |
500 | 287 Code blocks can import modules, define classes and functions, and basically do |
288 anything you can do in normal Python code. What code blocks can *not* do is to | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
289 produce content that is emitted directly tp the generated output. |
500 | 290 |
291 .. note:: Using the ``print`` statement will print to the standard output | |
292 stream, just as it does for other Python code in your application. | |
293 | |
294 Unlike expressions, Python code in ``<?python ?>`` processing instructions can | |
295 not use item and attribute access in an interchangeable manner. That means that | |
296 “dotted notation” is always attribute access, and vice-versa. | |
297 | |
298 The support for Python code blocks in templates is not supposed to encourage | |
299 mixing application code into templates, which is generally considered bad | |
300 design. If you're using many code blocks, that may be a sign that you should | |
301 move such code into separate Python modules. | |
302 | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
303 If you'd rather not allow the use of Python code blocks in templates, you can |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
304 simply set the ``allow_exec`` parameter (available on the ``Template`` and the |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
305 ``TemplateLoader`` initializers) to ``False``. In that case Genshi will raise |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
306 a syntax error when a ``<?python ?>`` processing instruction is encountered. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
307 But please note that disallowing code blocks in templates does not turn Genshi |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
308 into a sandboxable template engine; there are sufficient ways to do harm even |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
309 using plain expressions. |
500 | 310 |
311 | |
312 .. _`error handling`: | |
313 | |
314 Error Handling | |
315 ============== | |
316 | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
317 By default, Genshi raises an ``UndefinedError`` if a template expression |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
318 attempts to access a variable that is not defined: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
319 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
320 .. code-block:: pycon |
500 | 321 |
322 >>> from genshi.template import MarkupTemplate | |
323 >>> tmpl = MarkupTemplate('<p>${doh}</p>') | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
324 >>> tmpl.generate().render('xhtml') |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
325 Traceback (most recent call last): |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
326 ... |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
327 UndefinedError: "doh" not defined |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
328 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
329 You can change this behavior by setting the variable lookup mode to "lenient". |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
330 In that case, accessing undefined variables returns an `Undefined` object, |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
331 meaning that the expression does not fail immediately. See below for details. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
332 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
333 If you need to check whether a variable exists in the template context, use the |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
334 defined_ or the value_of_ function described below. To check for existence of |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
335 attributes on an object, or keys in a dictionary, use the ``hasattr()``, |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
336 ``getattr()`` or ``get()`` functions, or the ``in`` operator, just as you would |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
337 in regular Python code: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
338 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
339 >>> from genshi.template import MarkupTemplate |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
340 >>> tmpl = MarkupTemplate('<p>${defined("doh")}</p>') |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
341 >>> print tmpl.generate().render('xhtml') |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
342 <p>False</p> |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
343 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
344 .. note:: Lenient error handling was the default in Genshi prior to version 0.5. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
345 Strict mode was introduced in version 0.4, and became the default in |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
346 0.5. The reason for this change was that the lenient error handling |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
347 was masking actual errors in templates, thereby also making it harder |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
348 to debug some problems. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
349 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
350 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
351 .. _`lenient`: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
352 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
353 Lenient Mode |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
354 ------------ |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
355 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
356 If you instruct Genshi to use the lenient variable lookup mode, it allows you |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
357 to access variables that are not defined, without raising an ``UndefinedError``. |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
358 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
359 This mode can be chosen by passing the ``lookup='lenient'`` keyword argument to |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
360 the template initializer, or by passing the ``variable_lookup='lenient'`` |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
361 keyword argument to the ``TemplateLoader`` initializer: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
362 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
363 .. code-block:: pycon |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
364 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
365 >>> from genshi.template import MarkupTemplate |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
366 >>> tmpl = MarkupTemplate('<p>${doh}</p>', lookup='lenient') |
500 | 367 >>> print tmpl.generate().render('xhtml') |
368 <p></p> | |
369 | |
370 You *will* however get an exception if you try to call an undefined variable, or | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
371 do anything else with it, such as accessing its attributes: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
372 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
373 .. code-block:: pycon |
500 | 374 |
375 >>> from genshi.template import MarkupTemplate | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
376 >>> tmpl = MarkupTemplate('<p>${doh.oops}</p>', lookup='lenient') |
500 | 377 >>> print tmpl.generate().render('xhtml') |
378 Traceback (most recent call last): | |
379 ... | |
380 UndefinedError: "doh" not defined | |
381 | |
382 If you need to know whether a variable is defined, you can check its type | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
383 against the ``Undefined`` class, for example in a conditional directive: |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
384 |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
385 .. code-block:: pycon |
500 | 386 |
387 >>> from genshi.template import MarkupTemplate | |
820
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
388 >>> tmpl = MarkupTemplate('<p>${type(doh) is not Undefined}</p>', |
9755836bb396
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
389 ... lookup='lenient') |
500 | 390 >>> print tmpl.generate().render('xhtml') |
391 <p>False</p> | |
392 | |
393 Alternatively, the built-in functions defined_ or value_of_ can be used in this | |
394 case. | |
395 | |
396 Custom Modes | |
397 ------------ | |
398 | |
399 In addition to the built-in "lenient" and "strict" modes, it is also possible to | |
400 use a custom error handling mode. For example, you could use lenient error | |
401 handling in a production environment, while also logging a warning when an | |
402 undefined variable is referenced. | |
403 | |
404 See the API documentation of the ``genshi.template.eval`` module for details. | |
405 | |
406 | |
407 Built-in Functions & Types | |
408 ========================== | |
409 | |
410 The following functions and types are available by default in template code, in | |
411 addition to the standard built-ins that are available to all Python code. | |
412 | |
413 .. _`defined`: | |
414 | |
415 ``defined(name)`` | |
416 ----------------- | |
417 This function determines whether a variable of the specified name exists in | |
418 the context data, and returns ``True`` if it does. | |
419 | |
420 .. _`value_of`: | |
421 | |
422 ``value_of(name, default=None)`` | |
423 -------------------------------- | |
424 This function returns the value of the variable with the specified name if | |
425 such a variable is defined, and returns the value of the ``default`` | |
426 parameter if no such variable is defined. | |
427 | |
428 .. _`Markup`: | |
429 | |
430 ``Markup(text)`` | |
431 ---------------- | |
432 The ``Markup`` type marks a given string as being safe for inclusion in markup, | |
433 meaning it will *not* be escaped in the serialization stage. Use this with care, | |
434 as not escaping a user-provided string may allow malicious users to open your | |
435 web site to cross-site scripting attacks. | |
436 | |
437 .. _`Undefined`: | |
438 | |
439 ``Undefined`` | |
440 ---------------- | |
441 The ``Undefined`` type can be used to check whether a reference variable is | |
442 defined, as explained in `error handling`_. | |
443 | |
444 | |
445 .. _`directives`: | |
446 | |
447 ------------------- | |
448 Template Directives | |
449 ------------------- | |
450 | |
451 Directives provide control flow functionality for templates, such as conditions | |
452 or iteration. As the syntax for directives depends on whether you're using | |
453 markup or text templates, refer to the | |
454 `XML Template Language <xml-templates.html>`_ or | |
455 `Text Template Language <text-templates.html>`_ pages for information. |