Mercurial > genshi > genshi-test
comparison doc/xml-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 |
comparison
equal
deleted
inserted
replaced
500:0742f421caba | 820:1837f39efd6f |
---|---|
40 by the namespace ``http://genshi.edgewall.org/``. They can affect how the | 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 | 41 template is rendered in a number of ways: Genshi provides directives for |
42 conditionals and looping, among others. | 42 conditionals and looping, among others. |
43 | 43 |
44 To use directives in a template, the namespace must be declared, which is | 44 To use directives in a template, the namespace must be declared, which is |
45 usually done on the root element:: | 45 usually done on the root element: |
46 | |
47 .. code-block:: genshi | |
46 | 48 |
47 <html xmlns="http://www.w3.org/1999/xhtml" | 49 <html xmlns="http://www.w3.org/1999/xhtml" |
48 xmlns:py="http://genshi.edgewall.org/" | 50 xmlns:py="http://genshi.edgewall.org/" |
49 lang="en"> | 51 lang="en"> |
50 ... | 52 ... |
53 In this example, the default namespace is set to the XHTML namespace, and the | 55 In this example, the default namespace is set to the XHTML namespace, and the |
54 namespace for Genshi directives is bound to the prefix “py”. | 56 namespace for Genshi directives is bound to the prefix “py”. |
55 | 57 |
56 All directives can be applied as attributes, and some can also be used as | 58 All directives can be applied as attributes, and some can also be used as |
57 elements. The ``if`` directives for conditionals, for example, can be used in | 59 elements. The ``if`` directives for conditionals, for example, can be used in |
58 both ways:: | 60 both ways: |
61 | |
62 .. code-block:: genshi | |
59 | 63 |
60 <html xmlns="http://www.w3.org/1999/xhtml" | 64 <html xmlns="http://www.w3.org/1999/xhtml" |
61 xmlns:py="http://genshi.edgewall.org/" | 65 xmlns:py="http://genshi.edgewall.org/" |
62 lang="en"> | 66 lang="en"> |
63 ... | 67 ... |
65 <p>Bar</p> | 69 <p>Bar</p> |
66 </div> | 70 </div> |
67 ... | 71 ... |
68 </html> | 72 </html> |
69 | 73 |
70 This is basically equivalent to the following:: | 74 This is basically equivalent to the following: |
75 | |
76 .. code-block:: genshi | |
71 | 77 |
72 <html xmlns="http://www.w3.org/1999/xhtml" | 78 <html xmlns="http://www.w3.org/1999/xhtml" |
73 xmlns:py="http://genshi.edgewall.org/" | 79 xmlns:py="http://genshi.edgewall.org/" |
74 lang="en"> | 80 lang="en"> |
75 ... | 81 ... |
93 .. _`py:if`: | 99 .. _`py:if`: |
94 | 100 |
95 ``py:if`` | 101 ``py:if`` |
96 --------- | 102 --------- |
97 | 103 |
98 The element is only rendered if the expression evaluates to a truth value:: | 104 The element and its content is only rendered if the expression evaluates to a |
105 truth value: | |
106 | |
107 .. code-block:: genshi | |
99 | 108 |
100 <div> | 109 <div> |
101 <b py:if="foo">${bar}</b> | 110 <b py:if="foo">${bar}</b> |
102 </div> | 111 </div> |
103 | 112 |
104 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this | 113 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this |
105 would produce:: | 114 would produce: |
115 | |
116 .. code-block:: xml | |
106 | 117 |
107 <div> | 118 <div> |
108 <b>Hello</b> | 119 <b>Hello</b> |
109 </div> | 120 </div> |
110 | 121 |
111 This directive can also be used as an element:: | 122 But setting ``foo=False`` would result in the following output: |
123 | |
124 .. code-block:: xml | |
125 | |
126 <div> | |
127 </div> | |
128 | |
129 This directive can also be used as an element: | |
130 | |
131 .. code-block:: genshi | |
112 | 132 |
113 <div> | 133 <div> |
114 <py:if test="foo"> | 134 <py:if test="foo"> |
115 <b>${bar}</b> | 135 <b>${bar}</b> |
116 </py:if> | 136 </py:if> |
127 and ``py:otherwise`` provides advanced conditional processing for rendering one | 147 and ``py:otherwise`` provides advanced conditional processing for rendering one |
128 of several alternatives. The first matching ``py:when`` branch is rendered, or, | 148 of several alternatives. The first matching ``py:when`` branch is rendered, or, |
129 if no ``py:when`` branch matches, the ``py:otherwise`` branch is rendered. | 149 if no ``py:when`` branch matches, the ``py:otherwise`` branch is rendered. |
130 | 150 |
131 If the ``py:choose`` directive is empty the nested ``py:when`` directives will | 151 If the ``py:choose`` directive is empty the nested ``py:when`` directives will |
132 be tested for truth:: | 152 be tested for truth: |
153 | |
154 .. code-block:: genshi | |
133 | 155 |
134 <div py:choose=""> | 156 <div py:choose=""> |
135 <span py:when="0 == 1">0</span> | 157 <span py:when="0 == 1">0</span> |
136 <span py:when="1 == 1">1</span> | 158 <span py:when="1 == 1">1</span> |
137 <span py:otherwise="">2</span> | 159 <span py:otherwise="">2</span> |
138 </div> | 160 </div> |
139 | 161 |
140 This would produce the following output:: | 162 This would produce the following output: |
163 | |
164 .. code-block:: xml | |
141 | 165 |
142 <div> | 166 <div> |
143 <span>1</span> | 167 <span>1</span> |
144 </div> | 168 </div> |
145 | 169 |
146 If the ``py:choose`` directive contains an expression the nested ``py:when`` | 170 If the ``py:choose`` directive contains an expression the nested ``py:when`` |
147 directives will be tested for equality to the parent ``py:choose`` value:: | 171 directives will be tested for equality to the parent ``py:choose`` value: |
172 | |
173 .. code-block:: genshi | |
148 | 174 |
149 <div py:choose="1"> | 175 <div py:choose="1"> |
150 <span py:when="0">0</span> | 176 <span py:when="0">0</span> |
151 <span py:when="1">1</span> | 177 <span py:when="1">1</span> |
152 <span py:otherwise="">2</span> | 178 <span py:otherwise="">2</span> |
153 </div> | 179 </div> |
154 | 180 |
155 This would produce the following output:: | 181 This would produce the following output: |
182 | |
183 .. code-block:: xml | |
156 | 184 |
157 <div> | 185 <div> |
158 <span>1</span> | 186 <span>1</span> |
159 </div> | 187 </div> |
160 | 188 |
189 These directives can also be used as elements: | |
190 | |
191 .. code-block:: genshi | |
192 | |
193 <py:choose test="1"> | |
194 <py:when test="0">0</py:when> | |
195 <py:when test="1">1</py:when> | |
196 <py:otherwise>2</py:otherwise> | |
197 </py:choose> | |
161 | 198 |
162 Looping | 199 Looping |
163 ======= | 200 ======= |
164 | 201 |
165 .. _`py:for`: | 202 .. _`py:for`: |
166 | 203 |
167 ``py:for`` | 204 ``py:for`` |
168 ---------- | 205 ---------- |
169 | 206 |
170 The element is repeated for every item in an iterable:: | 207 The element is repeated for every item in an iterable: |
208 | |
209 .. code-block:: genshi | |
171 | 210 |
172 <ul> | 211 <ul> |
173 <li py:for="item in items">${item}</li> | 212 <li py:for="item in items">${item}</li> |
174 </ul> | 213 </ul> |
175 | 214 |
176 Given ``items=[1, 2, 3]`` in the context data, this would produce:: | 215 Given ``items=[1, 2, 3]`` in the context data, this would produce: |
216 | |
217 .. code-block:: xml | |
177 | 218 |
178 <ul> | 219 <ul> |
179 <li>1</li><li>2</li><li>3</li> | 220 <li>1</li><li>2</li><li>3</li> |
180 </ul> | 221 </ul> |
181 | 222 |
182 This directive can also be used as an element:: | 223 This directive can also be used as an element: |
224 | |
225 .. code-block:: genshi | |
183 | 226 |
184 <ul> | 227 <ul> |
185 <py:for each="item in items"> | 228 <py:for each="item in items"> |
186 <li>${item}</li> | 229 <li>${item}</li> |
187 </py:for> | 230 </py:for> |
197 ``py:def`` | 240 ``py:def`` |
198 ---------- | 241 ---------- |
199 | 242 |
200 The ``py:def`` directive can be used to create macros, i.e. snippets of | 243 The ``py:def`` directive can be used to create macros, i.e. snippets of |
201 template code that have a name and optionally some parameters, and that can be | 244 template code that have a name and optionally some parameters, and that can be |
202 inserted in other places:: | 245 inserted in other places: |
246 | |
247 .. code-block:: genshi | |
203 | 248 |
204 <div> | 249 <div> |
205 <p py:def="greeting(name)" class="greeting"> | 250 <p py:def="greeting(name)" class="greeting"> |
206 Hello, ${name}! | 251 Hello, ${name}! |
207 </p> | 252 </p> |
208 ${greeting('world')} | 253 ${greeting('world')} |
209 ${greeting('everyone else')} | 254 ${greeting('everyone else')} |
210 </div> | 255 </div> |
211 | 256 |
212 The above would be rendered to:: | 257 The above would be rendered to: |
258 | |
259 .. code-block:: xml | |
213 | 260 |
214 <div> | 261 <div> |
215 <p class="greeting"> | 262 <p class="greeting"> |
216 Hello, world! | 263 Hello, world! |
217 </p> | 264 </p> |
219 Hello, everyone else! | 266 Hello, everyone else! |
220 </p> | 267 </p> |
221 </div> | 268 </div> |
222 | 269 |
223 If a macro doesn't require parameters, it can be defined without the | 270 If a macro doesn't require parameters, it can be defined without the |
224 parenthesis. For example:: | 271 parenthesis. For example: |
272 | |
273 .. code-block:: genshi | |
225 | 274 |
226 <div> | 275 <div> |
227 <p py:def="greeting" class="greeting"> | 276 <p py:def="greeting" class="greeting"> |
228 Hello, world! | 277 Hello, world! |
229 </p> | 278 </p> |
230 ${greeting()} | 279 ${greeting()} |
231 </div> | 280 </div> |
232 | 281 |
233 The above would be rendered to:: | 282 The above would be rendered to: |
283 | |
284 .. code-block:: xml | |
234 | 285 |
235 <div> | 286 <div> |
236 <p class="greeting"> | 287 <p class="greeting"> |
237 Hello, world! | 288 Hello, world! |
238 </p> | 289 </p> |
239 </div> | 290 </div> |
240 | 291 |
241 This directive can also be used as an element:: | 292 This directive can also be used as an element: |
293 | |
294 .. code-block:: genshi | |
242 | 295 |
243 <div> | 296 <div> |
244 <py:def function="greeting(name)"> | 297 <py:def function="greeting(name)"> |
245 <p class="greeting">Hello, ${name}!</p> | 298 <p class="greeting">Hello, ${name}!</p> |
246 </py:def> | 299 </py:def> |
256 This directive defines a *match template*: given an XPath expression, it | 309 This directive defines a *match template*: given an XPath expression, it |
257 replaces any element in the template that matches the expression with its own | 310 replaces any element in the template that matches the expression with its own |
258 content. | 311 content. |
259 | 312 |
260 For example, the match template defined in the following template matches any | 313 For example, the match template defined in the following template matches any |
261 element with the tag name “greeting”:: | 314 element with the tag name “greeting”: |
315 | |
316 .. code-block:: genshi | |
262 | 317 |
263 <div> | 318 <div> |
264 <span py:match="greeting"> | 319 <span py:match="greeting"> |
265 Hello ${select('@name')} | 320 Hello ${select('@name')} |
266 </span> | 321 </span> |
267 <greeting name="Dude" /> | 322 <greeting name="Dude" /> |
268 </div> | 323 </div> |
269 | 324 |
270 This would result in the following output:: | 325 This would result in the following output: |
326 | |
327 .. code-block:: xml | |
271 | 328 |
272 <div> | 329 <div> |
273 <span> | 330 <span> |
274 Hello Dude | 331 Hello Dude |
275 </span> | 332 </span> |
280 in the output of the match template. See `Using XPath`_ for more information | 337 in the output of the match template. See `Using XPath`_ for more information |
281 about this function. | 338 about this function. |
282 | 339 |
283 .. _`Using XPath`: streams.html#using-xpath | 340 .. _`Using XPath`: streams.html#using-xpath |
284 | 341 |
285 This directive can also be used as an element:: | 342 Match templates are applied both to the original markup as well to the |
343 generated markup. The order in which they are applied depends on the order | |
344 they are declared in the template source: a match template defined after | |
345 another match template is applied to the output generated by the first match | |
346 template. The match templates basically form a pipeline. | |
347 | |
348 This directive can also be used as an element: | |
349 | |
350 .. code-block:: genshi | |
286 | 351 |
287 <div> | 352 <div> |
288 <py:match path="greeting"> | 353 <py:match path="greeting"> |
289 <span>Hello ${select('@name')}</span> | 354 <span>Hello ${select('@name')}</span> |
290 </py:match> | 355 </py:match> |
291 <greeting name="Dude" /> | 356 <greeting name="Dude" /> |
292 </div> | 357 </div> |
358 | |
359 When used this way, the ``py:match`` directive can also be annotated with a | |
360 couple of optimization hints. For example, the following informs the matching | |
361 engine that the match should only be applied once: | |
362 | |
363 .. code-block:: genshi | |
364 | |
365 <py:match path="body" once="true"> | |
366 <body py:attrs="select('@*')"> | |
367 <div id="header">...</div> | |
368 ${select("*|text()")} | |
369 <div id="footer">...</div> | |
370 </body> | |
371 </py:match> | |
372 | |
373 The following optimization hints are recognized: | |
374 | |
375 +---------------+-----------+-----------------------------------------------+ | |
376 | Attribute | Default | Description | | |
377 +===============+===========+===============================================+ | |
378 | ``buffer`` | ``true`` | Whether the matched content should be | | |
379 | | | buffered in memory. Buffering can improve | | |
380 | | | performance a bit at the cost of needing more | | |
381 | | | memory during rendering. Buffering is | | |
382 | | | ''required'' for match templates that contain | | |
383 | | | more than one invocation of the ``select()`` | | |
384 | | | function. If there is only one call, and the | | |
385 | | | matched content can potentially be very long, | | |
386 | | | consider disabling buffering to avoid | | |
387 | | | excessive memory use. | | |
388 +---------------+-----------+-----------------------------------------------+ | |
389 | ``once`` | ``false`` | Whether the engine should stop looking for | | |
390 | | | more matching elements after the first match. | | |
391 | | | Use this on match templates that match | | |
392 | | | elements that can only occur once in the | | |
393 | | | stream, such as the ``<head>`` or ``<body>`` | | |
394 | | | elements in an HTML template, or elements | | |
395 | | | with a specific ID. | | |
396 +---------------+-----------+-----------------------------------------------+ | |
397 | ``recursive`` | ``true`` | Whether the match template should be applied | | |
398 | | | to its own output. Note that ``once`` implies | | |
399 | | | non-recursive behavior, so this attribute | | |
400 | | | only needs to be set for match templates that | | |
401 | | | don't also have ``once`` set. | | |
402 +---------------+-----------+-----------------------------------------------+ | |
403 | |
404 .. note:: The ``py:match`` optimization hints were added in the 0.5 release. In | |
405 earlier versions, the attributes have no effect. | |
293 | 406 |
294 | 407 |
295 Variable Binding | 408 Variable Binding |
296 ================ | 409 ================ |
297 | 410 |
304 be used to make expressions inside the directive less verbose and more | 417 be used to make expressions inside the directive less verbose and more |
305 efficient. For example, if you need use the expression ``author.posts`` more | 418 efficient. For example, if you need use the expression ``author.posts`` more |
306 than once, and that actually results in a database query, assigning the results | 419 than once, and that actually results in a database query, assigning the results |
307 to a variable using this directive would probably help. | 420 to a variable using this directive would probably help. |
308 | 421 |
309 For example:: | 422 For example: |
423 | |
424 .. code-block:: genshi | |
310 | 425 |
311 <div> | 426 <div> |
312 <span py:with="y=7; z=x+10">$x $y $z</span> | 427 <span py:with="y=7; z=x+10">$x $y $z</span> |
313 </div> | 428 </div> |
314 | 429 |
315 Given ``x=42`` in the context data, this would produce:: | 430 Given ``x=42`` in the context data, this would produce: |
431 | |
432 .. code-block:: xml | |
316 | 433 |
317 <div> | 434 <div> |
318 <span>42 7 52</span> | 435 <span>42 7 52</span> |
319 </div> | 436 </div> |
320 | 437 |
321 This directive can also be used as an element:: | 438 This directive can also be used as an element: |
439 | |
440 .. code-block:: genshi | |
322 | 441 |
323 <div> | 442 <div> |
324 <py:with vars="y=7; z=x+10">$x $y $z</py:with> | 443 <py:with vars="y=7; z=x+10">$x $y $z</py:with> |
325 </div> | 444 </div> |
326 | 445 |
336 .. _`py:attrs`: | 455 .. _`py:attrs`: |
337 | 456 |
338 ``py:attrs`` | 457 ``py:attrs`` |
339 ------------ | 458 ------------ |
340 | 459 |
341 This directive adds, modifies or removes attributes from the element:: | 460 This directive adds, modifies or removes attributes from the element: |
461 | |
462 .. code-block:: genshi | |
342 | 463 |
343 <ul> | 464 <ul> |
344 <li py:attrs="foo">Bar</li> | 465 <li py:attrs="foo">Bar</li> |
345 </ul> | 466 </ul> |
346 | 467 |
347 Given ``foo={'class': 'collapse'}`` in the template context, this would | 468 Given ``foo={'class': 'collapse'}`` in the template context, this would |
348 produce:: | 469 produce: |
470 | |
471 .. code-block:: xml | |
349 | 472 |
350 <ul> | 473 <ul> |
351 <li class="collapse">Bar</li> | 474 <li class="collapse">Bar</li> |
352 </ul> | 475 </ul> |
353 | 476 |
354 Attributes with the value ``None`` are omitted, so given ``foo={'class': None}`` | 477 Attributes with the value ``None`` are omitted, so given ``foo={'class': None}`` |
355 in the context for the same template this would produce:: | 478 in the context for the same template this would produce: |
479 | |
480 .. code-block:: xml | |
356 | 481 |
357 <ul> | 482 <ul> |
358 <li>Bar</li> | 483 <li>Bar</li> |
359 </ul> | 484 </ul> |
360 | 485 |
365 | 490 |
366 ``py:content`` | 491 ``py:content`` |
367 -------------- | 492 -------------- |
368 | 493 |
369 This directive replaces any nested content with the result of evaluating the | 494 This directive replaces any nested content with the result of evaluating the |
370 expression:: | 495 expression: |
496 | |
497 .. code-block:: genshi | |
371 | 498 |
372 <ul> | 499 <ul> |
373 <li py:content="bar">Hello</li> | 500 <li py:content="bar">Hello</li> |
374 </ul> | 501 </ul> |
375 | 502 |
376 Given ``bar='Bye'`` in the context data, this would produce:: | 503 Given ``bar='Bye'`` in the context data, this would produce: |
504 | |
505 .. code-block:: xml | |
377 | 506 |
378 <ul> | 507 <ul> |
379 <li>Bye</li> | 508 <li>Bye</li> |
380 </ul> | 509 </ul> |
381 | 510 |
386 | 515 |
387 ``py:replace`` | 516 ``py:replace`` |
388 -------------- | 517 -------------- |
389 | 518 |
390 This directive replaces the element itself with the result of evaluating the | 519 This directive replaces the element itself with the result of evaluating the |
391 expression:: | 520 expression: |
521 | |
522 .. code-block:: genshi | |
392 | 523 |
393 <div> | 524 <div> |
394 <span py:replace="bar">Hello</span> | 525 <span py:replace="bar">Hello</span> |
395 </div> | 526 </div> |
396 | 527 |
397 Given ``bar='Bye'`` in the context data, this would produce:: | 528 Given ``bar='Bye'`` in the context data, this would produce: |
529 | |
530 .. code-block:: xml | |
398 | 531 |
399 <div> | 532 <div> |
400 Bye | 533 Bye |
401 </div> | 534 </div> |
402 | 535 |
403 This directive can only be used as an attribute. | 536 This directive can also be used as an element (since version 0.5): |
537 | |
538 .. code-block:: genshi | |
539 | |
540 <div> | |
541 <py:replace value="title">Placeholder</py:replace> | |
542 </div> | |
543 | |
404 | 544 |
405 | 545 |
406 .. _`py:strip`: | 546 .. _`py:strip`: |
407 | 547 |
408 ``py:strip`` | 548 ``py:strip`` |
409 ------------ | 549 ------------ |
410 | 550 |
411 This directive conditionally strips the top-level element from the output. When | 551 This directive conditionally strips the top-level element from the output. When |
412 the value of the ``py:strip`` attribute evaluates to ``True``, the element is | 552 the value of the ``py:strip`` attribute evaluates to ``True``, the element is |
413 stripped from the output:: | 553 stripped from the output: |
554 | |
555 .. code-block:: genshi | |
414 | 556 |
415 <div> | 557 <div> |
416 <div py:strip="True"><b>foo</b></div> | 558 <div py:strip="True"><b>foo</b></div> |
417 </div> | 559 </div> |
418 | 560 |
419 This would be rendered as:: | 561 This would be rendered as: |
562 | |
563 .. code-block:: xml | |
420 | 564 |
421 <div> | 565 <div> |
422 <b>foo</b> | 566 <b>foo</b> |
423 </div> | 567 </div> |
424 | 568 |
460 | 604 |
461 .. _xinclude: http://www.w3.org/TR/xinclude/ | 605 .. _xinclude: http://www.w3.org/TR/xinclude/ |
462 | 606 |
463 For this, you need to declare the XInclude namespace (commonly bound to the | 607 For this, you need to declare the XInclude namespace (commonly bound to the |
464 prefix “xi”) and use the ``<xi:include>`` element where you want the external | 608 prefix “xi”) and use the ``<xi:include>`` element where you want the external |
465 file to be pulled in:: | 609 file to be pulled in: |
610 | |
611 .. code-block:: genshi | |
466 | 612 |
467 <html xmlns="http://www.w3.org/1999/xhtml" | 613 <html xmlns="http://www.w3.org/1999/xhtml" |
468 xmlns:py="http://genshi.edgewall.org/" | 614 xmlns:py="http://genshi.edgewall.org/" |
469 xmlns:xi="http://www.w3.org/2001/XInclude"> | 615 xmlns:xi="http://www.w3.org/2001/XInclude"> |
470 <xi:include href="base.html" /> | 616 <xi:include href="base.html" /> |
483 the including template after the point it was included. | 629 the including template after the point it was included. |
484 | 630 |
485 By default, an error will be raised if an included file is not found. If that's | 631 By default, an error will be raised if an included file is not found. If that's |
486 not what you want, you can specify fallback content that should be used if the | 632 not what you want, you can specify fallback content that should be used if the |
487 include fails. For example, to to make the include above fail silently, you'd | 633 include fails. For example, to to make the include above fail silently, you'd |
488 write:: | 634 write: |
635 | |
636 .. code-block:: genshi | |
489 | 637 |
490 <xi:include href="base.html"><xi:fallback /></xi:include> | 638 <xi:include href="base.html"><xi:fallback /></xi:include> |
491 | 639 |
492 See the `XInclude specification`_ for more about fallback content. Note though | 640 See the `XInclude specification`_ for more about fallback content. Note though |
493 that Genshi currently only supports a small subset of XInclude. | 641 that Genshi currently only supports a small subset of XInclude. |
494 | 642 |
495 .. _`xinclude specification`: http://www.w3.org/TR/xinclude/ | 643 .. _`xinclude specification`: http://www.w3.org/TR/xinclude/ |
644 | |
645 | |
646 Dynamic Includes | |
647 ================ | |
496 | 648 |
497 Incudes in Genshi are fully dynamic: Just like normal attributes, the `href` | 649 Incudes in Genshi are fully dynamic: Just like normal attributes, the `href` |
498 attribute accepts expressions, and directives_ can be used on the | 650 attribute accepts expressions, and directives_ can be used on the |
499 ``<xi:include />`` element just as on any other element, meaning you can do | 651 ``<xi:include />`` element just as on any other element, meaning you can do |
500 things like conditional includes:: | 652 things like conditional includes: |
653 | |
654 .. code-block:: genshi | |
501 | 655 |
502 <xi:include href="${name}.html" py:if="not in_popup" | 656 <xi:include href="${name}.html" py:if="not in_popup" |
503 py:for="name in ('foo', 'bar', 'baz')" /> | 657 py:for="name in ('foo', 'bar', 'baz')" /> |
658 | |
659 | |
660 Including Text Templates | |
661 ======================== | |
662 | |
663 The ``parse`` attribute of the ``<xi:include>`` element can be used to specify | |
664 whether the included template is an XML template or a text template (using the | |
665 new syntax added in Genshi 0.5): | |
666 | |
667 .. code-block:: genshi | |
668 | |
669 <xi:include href="myscript.js" parse="text" /> | |
670 | |
671 This example would load the ``myscript.js`` file as a ``NewTextTemplate``. See | |
672 `text templates`_ for details on the syntax of text templates. | |
673 | |
674 .. _`text templates`: text-templates.html | |
504 | 675 |
505 | 676 |
506 .. _comments: | 677 .. _comments: |
507 | 678 |
508 -------- | 679 -------- |
509 Comments | 680 Comments |
510 -------- | 681 -------- |
511 | 682 |
512 Normal XML/HTML comment syntax can be used in templates:: | 683 Normal XML/HTML comment syntax can be used in templates: |
684 | |
685 .. code-block:: genshi | |
513 | 686 |
514 <!-- this is a comment --> | 687 <!-- this is a comment --> |
515 | 688 |
516 However, such comments get passed through the processing pipeline and are by | 689 However, such comments get passed through the processing pipeline and are by |
517 default included in the final output. If that's not desired, prefix the comment | 690 default included in the final output. If that's not desired, prefix the comment |
518 text with an exclamation mark:: | 691 text with an exclamation mark: |
692 | |
693 .. code-block:: genshi | |
519 | 694 |
520 <!-- !this is a comment too, but one that will be stripped from the output --> | 695 <!-- !this is a comment too, but one that will be stripped from the output --> |
521 | 696 |
522 Note that it does not matter whether there's whitespace before or after the | 697 Note that it does not matter whether there's whitespace before or after the |
523 exclamation mark, so the above could also be written as follows:: | 698 exclamation mark, so the above could also be written as follows: |
699 | |
700 .. code-block:: genshi | |
524 | 701 |
525 <!--! this is a comment too, but one that will be stripped from the output --> | 702 <!--! this is a comment too, but one that will be stripped from the output --> |