Mercurial > genshi > mirror
annotate doc/xml-templates.txt @ 700:08f22328303d trunk
Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
author | cmlenz |
---|---|
date | Fri, 28 Mar 2008 14:14:26 +0000 |
parents | 07e3f6f0ef57 |
children | 85ff66a8f453 |
rev | line source |
---|---|
226 | 1 .. -*- mode: rst; encoding: utf-8 -*- |
2 | |
3 ============================ | |
230 | 4 Genshi XML Template Language |
226 | 5 ============================ |
6 | |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
237
diff
changeset
|
7 Genshi provides a XML-based template language that is heavily inspired by Kid_, |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
237
diff
changeset
|
8 which in turn was inspired by a number of existing template languages, namely |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
237
diff
changeset
|
9 XSLT_, TAL_, and PHP_. |
226 | 10 |
11 .. _kid: http://kid-templating.org/ | |
12 .. _python: http://www.python.org/ | |
13 .. _xslt: http://www.w3.org/TR/xslt | |
14 .. _tal: http://www.zope.org/Wikis/DevSite/Projects/ZPT/TAL | |
15 .. _php: http://www.php.net/ | |
16 | |
17 This document describes the template language and will be most useful as | |
241
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
237
diff
changeset
|
18 reference to those developing Genshi XML templates. Templates are XML files of |
4d81439bc097
* Added basic documentation for the text-based template language.
cmlenz
parents:
237
diff
changeset
|
19 some kind (such as XHTML) that include processing directives_ (elements or |
226 | 20 attributes identified by a separate namespace) that affect how the template is |
442
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
429
diff
changeset
|
21 rendered, and template expressions that are dynamically substituted by |
226 | 22 variable data. |
23 | |
442
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
429
diff
changeset
|
24 See `Genshi Templating Basics <templates.html>`_ for general information on |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
429
diff
changeset
|
25 embedding Python code in templates. |
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
429
diff
changeset
|
26 |
226 | 27 |
28 .. contents:: Contents | |
29 :depth: 3 | |
30 .. sectnum:: | |
31 | |
32 | |
33 .. _`directives`: | |
34 | |
35 ------------------- | |
36 Template Directives | |
37 ------------------- | |
38 | |
39 Directives are elements and/or attributes in the template that are identified | |
230 | 40 by the namespace ``http://genshi.edgewall.org/``. They can affect how the |
41 template is rendered in a number of ways: Genshi provides directives for | |
226 | 42 conditionals and looping, among others. |
43 | |
394 | 44 To use directives in a template, the namespace must be declared, which is |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
45 usually done on the root element: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
46 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
47 .. code-block:: genshi |
226 | 48 |
49 <html xmlns="http://www.w3.org/1999/xhtml" | |
230 | 50 xmlns:py="http://genshi.edgewall.org/" |
226 | 51 lang="en"> |
52 ... | |
53 </html> | |
54 | |
55 In this example, the default namespace is set to the XHTML namespace, and the | |
230 | 56 namespace for Genshi directives is bound to the prefix “py”. |
226 | 57 |
58 All directives can be applied as attributes, and some can also be used as | |
59 elements. The ``if`` directives for conditionals, for example, can be used in | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
60 both ways: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
61 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
62 .. code-block:: genshi |
226 | 63 |
64 <html xmlns="http://www.w3.org/1999/xhtml" | |
230 | 65 xmlns:py="http://genshi.edgewall.org/" |
226 | 66 lang="en"> |
67 ... | |
68 <div py:if="foo"> | |
69 <p>Bar</p> | |
70 </div> | |
71 ... | |
72 </html> | |
73 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
74 This is basically equivalent to the following: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
75 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
76 .. code-block:: genshi |
226 | 77 |
78 <html xmlns="http://www.w3.org/1999/xhtml" | |
230 | 79 xmlns:py="http://genshi.edgewall.org/" |
226 | 80 lang="en"> |
81 ... | |
82 <py:if test="foo"> | |
83 <div> | |
84 <p>Bar</p> | |
85 </div> | |
86 </py:if> | |
87 ... | |
88 </html> | |
89 | |
90 The rationale behind the second form is that directives do not always map | |
91 naturally to elements in the template. In such cases, the ``py:strip`` | |
92 directive can be used to strip off the unwanted element, or the directive can | |
93 simply be used as an element. | |
94 | |
95 | |
237 | 96 Conditional Sections |
226 | 97 ==================== |
98 | |
235 | 99 .. _`py:if`: |
226 | 100 |
235 | 101 ``py:if`` |
237 | 102 --------- |
226 | 103 |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
104 The element is only rendered if the expression evaluates to a truth value: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
105 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
106 .. code-block:: genshi |
226 | 107 |
235 | 108 <div> |
109 <b py:if="foo">${bar}</b> | |
110 </div> | |
226 | 111 |
235 | 112 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
113 would produce: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
114 |
612
3d2909fe1dda
Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents:
610
diff
changeset
|
115 .. code-block:: xml |
235 | 116 |
117 <div> | |
118 <b>Hello</b> | |
119 </div> | |
120 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
121 This directive can also be used as an element: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
122 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
123 .. code-block:: genshi |
235 | 124 |
125 <div> | |
126 <py:if test="foo"> | |
127 <b>${bar}</b> | |
128 </py:if> | |
129 </div> | |
226 | 130 |
131 .. _`py:choose`: | |
132 .. _`py:when`: | |
133 .. _`py:otherwise`: | |
134 | |
237 | 135 ``py:choose`` |
136 ------------- | |
226 | 137 |
237 | 138 The ``py:choose`` directive, in combination with the directives ``py:when`` |
404 | 139 and ``py:otherwise`` provides advanced conditional processing for rendering one |
226 | 140 of several alternatives. The first matching ``py:when`` branch is rendered, or, |
404 | 141 if no ``py:when`` branch matches, the ``py:otherwise`` branch is rendered. |
226 | 142 |
143 If the ``py:choose`` directive is empty the nested ``py:when`` directives will | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
144 be tested for truth: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
145 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
146 .. code-block:: genshi |
226 | 147 |
148 <div py:choose=""> | |
149 <span py:when="0 == 1">0</span> | |
150 <span py:when="1 == 1">1</span> | |
151 <span py:otherwise="">2</span> | |
152 </div> | |
153 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
154 This would produce the following output: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
155 |
612
3d2909fe1dda
Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents:
610
diff
changeset
|
156 .. code-block:: xml |
226 | 157 |
158 <div> | |
159 <span>1</span> | |
160 </div> | |
161 | |
162 If the ``py:choose`` directive contains an expression the nested ``py:when`` | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
163 directives will be tested for equality to the parent ``py:choose`` value: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
164 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
165 .. code-block:: genshi |
226 | 166 |
167 <div py:choose="1"> | |
168 <span py:when="0">0</span> | |
169 <span py:when="1">1</span> | |
170 <span py:otherwise="">2</span> | |
171 </div> | |
172 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
173 This would produce the following output: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
174 |
612
3d2909fe1dda
Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents:
610
diff
changeset
|
175 .. code-block:: xml |
226 | 176 |
177 <div> | |
178 <span>1</span> | |
179 </div> | |
180 | |
181 | |
235 | 182 Looping |
237 | 183 ======= |
226 | 184 |
235 | 185 .. _`py:for`: |
226 | 186 |
235 | 187 ``py:for`` |
237 | 188 ---------- |
235 | 189 |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
190 The element is repeated for every item in an iterable: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
191 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
192 .. code-block:: genshi |
226 | 193 |
194 <ul> | |
235 | 195 <li py:for="item in items">${item}</li> |
226 | 196 </ul> |
197 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
198 Given ``items=[1, 2, 3]`` in the context data, this would produce: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
199 |
612
3d2909fe1dda
Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents:
610
diff
changeset
|
200 .. code-block:: xml |
226 | 201 |
202 <ul> | |
235 | 203 <li>1</li><li>2</li><li>3</li> |
226 | 204 </ul> |
205 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
206 This directive can also be used as an element: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
207 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
208 .. code-block:: genshi |
226 | 209 |
235 | 210 <ul> |
211 <py:for each="item in items"> | |
212 <li>${item}</li> | |
213 </py:for> | |
214 </ul> | |
215 | |
216 | |
217 Snippet Reuse | |
237 | 218 ============= |
226 | 219 |
220 .. _`py:def`: | |
221 .. _`macros`: | |
222 | |
223 ``py:def`` | |
237 | 224 ---------- |
226 | 225 |
226 The ``py:def`` directive can be used to create macros, i.e. snippets of | |
227 template code that have a name and optionally some parameters, and that can be | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
228 inserted in other places: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
229 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
230 .. code-block:: genshi |
226 | 231 |
232 <div> | |
233 <p py:def="greeting(name)" class="greeting"> | |
234 Hello, ${name}! | |
235 </p> | |
236 ${greeting('world')} | |
237 ${greeting('everyone else')} | |
238 </div> | |
239 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
240 The above would be rendered to: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
241 |
612
3d2909fe1dda
Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents:
610
diff
changeset
|
242 .. code-block:: xml |
226 | 243 |
244 <div> | |
245 <p class="greeting"> | |
246 Hello, world! | |
247 </p> | |
248 <p class="greeting"> | |
249 Hello, everyone else! | |
250 </p> | |
251 </div> | |
252 | |
394 | 253 If a macro doesn't require parameters, it can be defined without the |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
254 parenthesis. For example: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
255 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
256 .. code-block:: genshi |
226 | 257 |
258 <div> | |
259 <p py:def="greeting" class="greeting"> | |
260 Hello, world! | |
261 </p> | |
394 | 262 ${greeting()} |
226 | 263 </div> |
264 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
265 The above would be rendered to: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
266 |
612
3d2909fe1dda
Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents:
610
diff
changeset
|
267 .. code-block:: xml |
226 | 268 |
269 <div> | |
270 <p class="greeting"> | |
271 Hello, world! | |
272 </p> | |
273 </div> | |
274 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
275 This directive can also be used as an element: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
276 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
277 .. code-block:: genshi |
226 | 278 |
279 <div> | |
280 <py:def function="greeting(name)"> | |
281 <p class="greeting">Hello, ${name}!</p> | |
282 </py:def> | |
283 </div> | |
284 | |
285 | |
235 | 286 .. _Match Templates: |
226 | 287 .. _`py:match`: |
288 | |
289 ``py:match`` | |
237 | 290 ------------ |
226 | 291 |
292 This directive defines a *match template*: given an XPath expression, it | |
293 replaces any element in the template that matches the expression with its own | |
294 content. | |
295 | |
296 For example, the match template defined in the following template matches any | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
297 element with the tag name “greeting”: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
298 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
299 .. code-block:: genshi |
226 | 300 |
301 <div> | |
302 <span py:match="greeting"> | |
303 Hello ${select('@name')} | |
304 </span> | |
305 <greeting name="Dude" /> | |
306 </div> | |
307 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
308 This would result in the following output: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
309 |
612
3d2909fe1dda
Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents:
610
diff
changeset
|
310 .. code-block:: xml |
226 | 311 |
312 <div> | |
313 <span> | |
314 Hello Dude | |
315 </span> | |
316 </div> | |
317 | |
318 Inside the body of a ``py:match`` directive, the ``select(path)`` function is | |
319 made available so that parts or all of the original element can be incorporated | |
451 | 320 in the output of the match template. See `Using XPath`_ for more information |
321 about this function. | |
322 | |
323 .. _`Using XPath`: streams.html#using-xpath | |
226 | 324 |
694
07e3f6f0ef57
Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case.
cmlenz
parents:
657
diff
changeset
|
325 Match templates are applied both to the original markup as well to the |
07e3f6f0ef57
Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case.
cmlenz
parents:
657
diff
changeset
|
326 generated markup. The order in which they are applied depends on the order |
07e3f6f0ef57
Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case.
cmlenz
parents:
657
diff
changeset
|
327 they are declared in the template source: a match template defined after |
07e3f6f0ef57
Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case.
cmlenz
parents:
657
diff
changeset
|
328 another match template is applied to the output generated by the first match |
07e3f6f0ef57
Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case.
cmlenz
parents:
657
diff
changeset
|
329 template. The match templates basically form a pipeline. |
07e3f6f0ef57
Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case.
cmlenz
parents:
657
diff
changeset
|
330 |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
331 This directive can also be used as an element: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
332 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
333 .. code-block:: genshi |
226 | 334 |
335 <div> | |
336 <py:match path="greeting"> | |
337 <span>Hello ${select('@name')}</span> | |
338 </py:match> | |
339 <greeting name="Dude" /> | |
340 </div> | |
341 | |
602 | 342 When used this way, the ``py:match`` directive can also be annotated with a |
343 couple of optimization hints. For example, the following informs the matching | |
344 engine that the match should only be applied once: | |
345 | |
346 .. code-block:: genshi | |
347 | |
348 <py:match path="body" once="true"> | |
349 <body py:attrs="select('@*')"> | |
350 <div id="header">...</div> | |
351 ${select("*|text()")} | |
352 <div id="footer">...</div> | |
353 </body> | |
354 </py:match> | |
355 | |
356 The following optimization hints are recognized: | |
357 | |
358 +---------------+-----------+-----------------------------------------------+ | |
359 | Attribute | Default | Description | | |
360 +===============+===========+===============================================+ | |
700
08f22328303d
Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents:
694
diff
changeset
|
361 | ``buffer`` | ``true`` | Whether the matched content should be | |
08f22328303d
Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents:
694
diff
changeset
|
362 | | | buffered in memory. Buffering can improve | |
08f22328303d
Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents:
694
diff
changeset
|
363 | | | performance a bit at the cost of needing more | |
08f22328303d
Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents:
694
diff
changeset
|
364 | | | memory during rendering. Buffering is | |
08f22328303d
Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents:
694
diff
changeset
|
365 | | | ''required'' for match templates that contain | |
08f22328303d
Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents:
694
diff
changeset
|
366 | | | more than one invocation of the ``select()`` | |
08f22328303d
Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents:
694
diff
changeset
|
367 | | | function. If there is only one call, and the | |
08f22328303d
Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents:
694
diff
changeset
|
368 | | | matched content can potentially be very long, | |
08f22328303d
Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents:
694
diff
changeset
|
369 | | | consider disabling buffering to avoid | |
08f22328303d
Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents:
694
diff
changeset
|
370 | | | excessive memory use. | |
08f22328303d
Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents:
694
diff
changeset
|
371 +---------------+-----------+-----------------------------------------------+ |
602 | 372 | ``once`` | ``false`` | Whether the engine should stop looking for | |
373 | | | more matching elements after the first match. | | |
374 | | | Use this on match templates that match | | |
375 | | | elements that can only occur once in the | | |
376 | | | stream, such as the ``<head>`` or ``<body>`` | | |
377 | | | elements in an HTML template, or elements | | |
378 | | | with a specific ID. | | |
379 +---------------+-----------+-----------------------------------------------+ | |
380 | ``recursive`` | ``true`` | Whether the match template should be applied | | |
381 | | | to its own output. Note that ``once`` implies | | |
382 | | | non-recursive behavior, so this attribute | | |
383 | | | only needs to be set for match templates that | | |
384 | | | don't also have ``once`` set. | | |
385 +---------------+-----------+-----------------------------------------------+ | |
386 | |
387 .. note:: The ``py:match`` optimization hints were added in the 0.5 release. In | |
388 earlier versions, the attributes have no effect. | |
389 | |
226 | 390 |
235 | 391 Variable Binding |
237 | 392 ================ |
226 | 393 |
394 .. _`with`: | |
395 | |
396 ``py:with`` | |
237 | 397 ----------- |
226 | 398 |
399 The ``py:with`` directive lets you assign expressions to variables, which can | |
400 be used to make expressions inside the directive less verbose and more | |
401 efficient. For example, if you need use the expression ``author.posts`` more | |
402 than once, and that actually results in a database query, assigning the results | |
403 to a variable using this directive would probably help. | |
404 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
405 For example: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
406 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
407 .. code-block:: genshi |
226 | 408 |
409 <div> | |
410 <span py:with="y=7; z=x+10">$x $y $z</span> | |
411 </div> | |
412 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
413 Given ``x=42`` in the context data, this would produce: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
414 |
612
3d2909fe1dda
Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents:
610
diff
changeset
|
415 .. code-block:: xml |
226 | 416 |
417 <div> | |
418 <span>42 7 52</span> | |
419 </div> | |
420 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
421 This directive can also be used as an element: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
422 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
423 .. code-block:: genshi |
226 | 424 |
425 <div> | |
426 <py:with vars="y=7; z=x+10">$x $y $z</py:with> | |
427 </div> | |
428 | |
429 Note that if a variable of the same name already existed outside of the scope | |
430 of the ``py:with`` directive, it will **not** be overwritten. Instead, it | |
431 will have the same value it had prior to the ``py:with`` assignment. | |
230 | 432 Effectively, this means that variables are immutable in Genshi. |
226 | 433 |
434 | |
235 | 435 Structure Manipulation |
237 | 436 ====================== |
235 | 437 |
438 .. _`py:attrs`: | |
439 | |
440 ``py:attrs`` | |
237 | 441 ------------ |
235 | 442 |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
443 This directive adds, modifies or removes attributes from the element: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
444 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
445 .. code-block:: genshi |
235 | 446 |
447 <ul> | |
448 <li py:attrs="foo">Bar</li> | |
449 </ul> | |
450 | |
451 Given ``foo={'class': 'collapse'}`` in the template context, this would | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
452 produce: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
453 |
612
3d2909fe1dda
Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents:
610
diff
changeset
|
454 .. code-block:: xml |
235 | 455 |
456 <ul> | |
457 <li class="collapse">Bar</li> | |
458 </ul> | |
459 | |
460 Attributes with the value ``None`` are omitted, so given ``foo={'class': None}`` | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
461 in the context for the same template this would produce: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
462 |
612
3d2909fe1dda
Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents:
610
diff
changeset
|
463 .. code-block:: xml |
235 | 464 |
465 <ul> | |
466 <li>Bar</li> | |
467 </ul> | |
468 | |
469 This directive can only be used as an attribute. | |
470 | |
471 | |
472 .. _`py:content`: | |
473 | |
474 ``py:content`` | |
237 | 475 -------------- |
235 | 476 |
477 This directive replaces any nested content with the result of evaluating the | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
478 expression: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
479 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
480 .. code-block:: genshi |
235 | 481 |
482 <ul> | |
483 <li py:content="bar">Hello</li> | |
484 </ul> | |
485 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
486 Given ``bar='Bye'`` in the context data, this would produce: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
487 |
612
3d2909fe1dda
Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents:
610
diff
changeset
|
488 .. code-block:: xml |
235 | 489 |
490 <ul> | |
491 <li>Bye</li> | |
492 </ul> | |
493 | |
494 This directive can only be used as an attribute. | |
495 | |
496 | |
497 .. _`py:replace`: | |
498 | |
499 ``py:replace`` | |
237 | 500 -------------- |
235 | 501 |
502 This directive replaces the element itself with the result of evaluating the | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
503 expression: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
504 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
505 .. code-block:: genshi |
235 | 506 |
507 <div> | |
508 <span py:replace="bar">Hello</span> | |
509 </div> | |
510 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
511 Given ``bar='Bye'`` in the context data, this would produce: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
512 |
612
3d2909fe1dda
Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents:
610
diff
changeset
|
513 .. code-block:: xml |
235 | 514 |
515 <div> | |
516 Bye | |
517 </div> | |
518 | |
657 | 519 This directive can also be used as an element (since version 0.5): |
520 | |
521 .. code-block:: genshi | |
522 | |
523 <div> | |
524 <py:replace value="title">Placeholder</py:replace> | |
525 </div> | |
526 | |
235 | 527 |
528 | |
529 .. _`py:strip`: | |
530 | |
531 ``py:strip`` | |
237 | 532 ------------ |
235 | 533 |
534 This directive conditionally strips the top-level element from the output. When | |
535 the value of the ``py:strip`` attribute evaluates to ``True``, the element is | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
536 stripped from the output: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
537 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
538 .. code-block:: genshi |
235 | 539 |
540 <div> | |
541 <div py:strip="True"><b>foo</b></div> | |
542 </div> | |
543 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
544 This would be rendered as: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
545 |
612
3d2909fe1dda
Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents:
610
diff
changeset
|
546 .. code-block:: xml |
235 | 547 |
548 <div> | |
549 <b>foo</b> | |
550 </div> | |
551 | |
552 As a shorthand, if the value of the ``py:strip`` attribute is empty, that has | |
553 the same effect as using a truth value (i.e. the element is stripped). | |
554 | |
555 | |
226 | 556 .. _order: |
557 | |
558 Processing Order | |
559 ================ | |
560 | |
561 It is possible to attach multiple directives to a single element, although not | |
562 all combinations make sense. When multiple directives are encountered, they are | |
563 processed in the following order: | |
564 | |
565 #. `py:def`_ | |
566 #. `py:match`_ | |
567 #. `py:when`_ | |
568 #. `py:otherwise`_ | |
569 #. `py:for`_ | |
570 #. `py:if`_ | |
571 #. `py:choose`_ | |
572 #. `py:with`_ | |
573 #. `py:replace`_ | |
574 #. `py:content`_ | |
575 #. `py:attrs`_ | |
576 #. `py:strip`_ | |
577 | |
578 | |
579 .. _includes: | |
580 | |
581 -------- | |
582 Includes | |
583 -------- | |
584 | |
585 To reuse common snippets of template code, you can include other files using | |
586 XInclude_. | |
587 | |
588 .. _xinclude: http://www.w3.org/TR/xinclude/ | |
589 | |
590 For this, you need to declare the XInclude namespace (commonly bound to the | |
591 prefix “xi”) and use the ``<xi:include>`` element where you want the external | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
592 file to be pulled in: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
593 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
594 .. code-block:: genshi |
226 | 595 |
596 <html xmlns="http://www.w3.org/1999/xhtml" | |
230 | 597 xmlns:py="http://genshi.edgewall.org/" |
226 | 598 xmlns:xi="http://www.w3.org/2001/XInclude"> |
599 <xi:include href="base.html" /> | |
600 ... | |
601 </html> | |
602 | |
603 Include paths are relative to the filename of the template currently being | |
604 processed. So if the example above was in the file "``myapp/index.html``" | |
605 (relative to the template search path), the XInclude processor would look for | |
606 the included file at "``myapp/base.html``". You can also use Unix-style | |
607 relative paths, for example "``../base.html``" to look in the parent directory. | |
608 | |
609 Any content included this way is inserted into the generated output instead of | |
610 the ``<xi:include>`` element. The included template sees the same context data. | |
611 `Match templates`_ and `macros`_ in the included template are also available to | |
612 the including template after the point it was included. | |
613 | |
614 By default, an error will be raised if an included file is not found. If that's | |
615 not what you want, you can specify fallback content that should be used if the | |
616 include fails. For example, to to make the include above fail silently, you'd | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
617 write: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
618 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
619 .. code-block:: genshi |
226 | 620 |
621 <xi:include href="base.html"><xi:fallback /></xi:include> | |
622 | |
273 | 623 See the `XInclude specification`_ for more about fallback content. Note though |
624 that Genshi currently only supports a small subset of XInclude. | |
625 | |
626 .. _`xinclude specification`: http://www.w3.org/TR/xinclude/ | |
226 | 627 |
610
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
628 |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
629 Dynamic Includes |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
630 ================ |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
631 |
230 | 632 Incudes in Genshi are fully dynamic: Just like normal attributes, the `href` |
442
97544725bb7f
Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents:
429
diff
changeset
|
633 attribute accepts expressions, and directives_ can be used on the |
226 | 634 ``<xi:include />`` element just as on any other element, meaning you can do |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
635 things like conditional includes: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
636 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
637 .. code-block:: genshi |
226 | 638 |
639 <xi:include href="${name}.html" py:if="not in_popup" | |
640 py:for="name in ('foo', 'bar', 'baz')" /> | |
641 | |
642 | |
610
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
643 Including Text Templates |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
644 ======================== |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
645 |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
646 The ``parse`` attribute of the ``<xi:include>`` element can be used to specify |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
647 whether the included template is an XML template or a text template (using the |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
648 new syntax added in Genshi 0.5): |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
649 |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
650 .. code-block:: genshi |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
651 |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
652 <xi:include href="myscript.js" parse="text" /> |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
653 |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
654 This example would load the ``myscript.js`` file as a ``NewTextTemplate``. See |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
655 `text templates`_ for details on the syntax of text templates. |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
656 |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
657 .. _`text templates`: text-templates.html |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
658 |
5e358de79e4c
* XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents:
602
diff
changeset
|
659 |
226 | 660 .. _comments: |
661 | |
662 -------- | |
663 Comments | |
664 -------- | |
665 | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
666 Normal XML/HTML comment syntax can be used in templates: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
667 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
668 .. code-block:: genshi |
226 | 669 |
670 <!-- this is a comment --> | |
671 | |
672 However, such comments get passed through the processing pipeline and are by | |
673 default included in the final output. If that's not desired, prefix the comment | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
674 text with an exclamation mark: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
675 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
676 .. code-block:: genshi |
226 | 677 |
678 <!-- !this is a comment too, but one that will be stripped from the output --> | |
679 | |
680 Note that it does not matter whether there's whitespace before or after the | |
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
681 exclamation mark, so the above could also be written as follows: |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
682 |
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
683 .. code-block:: genshi |
226 | 684 |
685 <!--! this is a comment too, but one that will be stripped from the output --> |