Mercurial > genshi > genshi-test
annotate doc/templates.txt @ 820:1837f39efd6f experimental-inline
Sync (old) experimental inline branch with trunk@1027.
| author | cmlenz |
|---|---|
| date | Wed, 11 Mar 2009 17:51:06 +0000 |
| parents | 0742f421caba |
| children | 09cc3627654c |
| 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
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
35 The following illustrates a very basic Genshi markup template: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
36 |
|
1837f39efd6f
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
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
65 The template would generate output similar to this: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
66 |
|
1837f39efd6f
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
1837f39efd6f
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: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
87 |
|
1837f39efd6f
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
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
112 For example: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
113 |
|
1837f39efd6f
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
1837f39efd6f
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
1837f39efd6f
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 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
123 information on configuring template output options. |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
124 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
125 Using a text template is similar: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
126 |
|
1837f39efd6f
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
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
132 >>> print stream |
| 500 | 133 Hello, world! |
| 134 | |
|
820
1837f39efd6f
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 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
136 ``NewTextTemplate`` class instead of simply ``TextTemplate``. See |
|
1837f39efd6f
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
1837f39efd6f
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
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
147 template loader would generally look as follows: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
148 |
|
1837f39efd6f
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
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
178 ends: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
179 |
|
1837f39efd6f
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
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
190 dictionary): |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
191 |
|
1837f39efd6f
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
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
206 Escaping |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
207 ======== |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
208 |
|
1837f39efd6f
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 |
|
1837f39efd6f
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: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
211 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
212 .. code-block:: pycon |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
213 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
214 >>> from genshi.template import MarkupTemplate |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
215 >>> tmpl = MarkupTemplate('<em>$foo</em>') # Wanted "$foo" as literal output |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
216 >>> print tmpl.generate() |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
217 Traceback (most recent call last): |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
218 ... |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
219 UndefinedError: "foo" not defined |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
220 >>> tmpl = MarkupTemplate('<em>$$foo</em>') |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
221 >>> print tmpl.generate() |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
222 <em>$foo</em> |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
223 |
|
1837f39efd6f
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 |
|
1837f39efd6f
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: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
226 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
227 .. code-block:: pycon |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
228 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
229 >>> tmpl = MarkupTemplate('<script>$(function() {})</script>') |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
230 >>> print tmpl.generate() |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
231 <script>$(function() {})</script> |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
232 |
|
1837f39efd6f
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 |
|
1837f39efd6f
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 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
235 output: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
236 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
237 .. code-block:: pycon |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
238 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
239 >>> tmpl = MarkupTemplate('<script>$$$("div")</script>') |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
240 >>> print tmpl.generate() |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
241 <script>$$("div")</script> |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
242 |
|
1837f39efd6f
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
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
249 Templates also support full Python code blocks, using the ``<?python ?>`` |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
250 processing instruction in XML templates: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
251 |
|
1837f39efd6f
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
1837f39efd6f
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
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
262 This will produce the following output: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
263 |
|
1837f39efd6f
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
1837f39efd6f
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 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
271 Genshi 0.5), code blocks use the special ``{% python %}`` directive: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
272 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
273 .. code-block:: genshitext |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
274 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
275 {% python |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
276 from genshi.builder import tag |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
277 def greeting(name): |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
278 return 'Hello, %s!' % name |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
279 %} |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
280 ${greeting('world')} |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
281 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
282 This will produce the following output:: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
283 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
284 Hello, world! |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
285 |
|
1837f39efd6f
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
1837f39efd6f
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
1837f39efd6f
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 |
|
1837f39efd6f
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 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
305 ``TemplateLoader`` initializers) to ``False``. In that case Genshi will raise |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
306 a syntax error when a ``<?python ?>`` processing instruction is encountered. |
|
1837f39efd6f
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 |
|
1837f39efd6f
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 |
|
1837f39efd6f
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
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
317 By default, Genshi raises an ``UndefinedError`` if a template expression |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
318 attempts to access a variable that is not defined: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
319 |
|
1837f39efd6f
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
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
324 >>> tmpl.generate().render('xhtml') |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
325 Traceback (most recent call last): |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
326 ... |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
327 UndefinedError: "doh" not defined |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
328 |
|
1837f39efd6f
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". |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
330 In that case, accessing undefined variables returns an `Undefined` object, |
|
1837f39efd6f
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. |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
332 |
|
1837f39efd6f
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 |
|
1837f39efd6f
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 |
|
1837f39efd6f
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()``, |
|
1837f39efd6f
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 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
337 in regular Python code: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
338 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
339 >>> from genshi.template import MarkupTemplate |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
340 >>> tmpl = MarkupTemplate('<p>${defined("doh")}</p>') |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
341 >>> print tmpl.generate().render('xhtml') |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
342 <p>False</p> |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
343 |
|
1837f39efd6f
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. |
|
1837f39efd6f
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 |
|
1837f39efd6f
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 |
|
1837f39efd6f
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 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
348 to debug some problems. |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
349 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
350 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
351 .. _`lenient`: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
352 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
353 Lenient Mode |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
354 ------------ |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
355 |
|
1837f39efd6f
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 |
|
1837f39efd6f
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``. |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
358 |
|
1837f39efd6f
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 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
360 the template initializer, or by passing the ``variable_lookup='lenient'`` |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
361 keyword argument to the ``TemplateLoader`` initializer: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
362 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
363 .. code-block:: pycon |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
364 |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
365 >>> from genshi.template import MarkupTemplate |
|
1837f39efd6f
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
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
371 do anything else with it, such as accessing its attributes: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
372 |
|
1837f39efd6f
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
1837f39efd6f
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
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
383 against the ``Undefined`` class, for example in a conditional directive: |
|
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
384 |
|
1837f39efd6f
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
1837f39efd6f
Sync (old) experimental inline branch with trunk@1027.
cmlenz
parents:
500
diff
changeset
|
388 >>> tmpl = MarkupTemplate('<p>${type(doh) is not Undefined}</p>', |
|
1837f39efd6f
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. |