Mercurial > genshi > genshi-test
comparison doc/xml-templates.txt @ 510:ca7d707d51b0
Use syntax highlighting on all the other doc pages, too.
author | cmlenz |
---|---|
date | Wed, 06 Jun 2007 10:41:41 +0000 |
parents | bcc1d6c67a2f |
children | 509b3a5e765e f725e48c9a5f f0bb2c5ea0ff |
comparison
equal
deleted
inserted
replaced
509:1997f7af845c | 510:ca7d707d51b0 |
---|---|
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 is only rendered if the expression evaluates to a truth value: |
105 | |
106 .. code-block:: genshi | |
99 | 107 |
100 <div> | 108 <div> |
101 <b py:if="foo">${bar}</b> | 109 <b py:if="foo">${bar}</b> |
102 </div> | 110 </div> |
103 | 111 |
104 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this | 112 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this |
105 would produce:: | 113 would produce: |
114 | |
115 .. code-block:: html | |
106 | 116 |
107 <div> | 117 <div> |
108 <b>Hello</b> | 118 <b>Hello</b> |
109 </div> | 119 </div> |
110 | 120 |
111 This directive can also be used as an element:: | 121 This directive can also be used as an element: |
122 | |
123 .. code-block:: genshi | |
112 | 124 |
113 <div> | 125 <div> |
114 <py:if test="foo"> | 126 <py:if test="foo"> |
115 <b>${bar}</b> | 127 <b>${bar}</b> |
116 </py:if> | 128 </py:if> |
127 and ``py:otherwise`` provides advanced conditional processing for rendering one | 139 and ``py:otherwise`` provides advanced conditional processing for rendering one |
128 of several alternatives. The first matching ``py:when`` branch is rendered, or, | 140 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. | 141 if no ``py:when`` branch matches, the ``py:otherwise`` branch is rendered. |
130 | 142 |
131 If the ``py:choose`` directive is empty the nested ``py:when`` directives will | 143 If the ``py:choose`` directive is empty the nested ``py:when`` directives will |
132 be tested for truth:: | 144 be tested for truth: |
145 | |
146 .. code-block:: genshi | |
133 | 147 |
134 <div py:choose=""> | 148 <div py:choose=""> |
135 <span py:when="0 == 1">0</span> | 149 <span py:when="0 == 1">0</span> |
136 <span py:when="1 == 1">1</span> | 150 <span py:when="1 == 1">1</span> |
137 <span py:otherwise="">2</span> | 151 <span py:otherwise="">2</span> |
138 </div> | 152 </div> |
139 | 153 |
140 This would produce the following output:: | 154 This would produce the following output: |
155 | |
156 .. code-block:: html | |
141 | 157 |
142 <div> | 158 <div> |
143 <span>1</span> | 159 <span>1</span> |
144 </div> | 160 </div> |
145 | 161 |
146 If the ``py:choose`` directive contains an expression the nested ``py:when`` | 162 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:: | 163 directives will be tested for equality to the parent ``py:choose`` value: |
164 | |
165 .. code-block:: genshi | |
148 | 166 |
149 <div py:choose="1"> | 167 <div py:choose="1"> |
150 <span py:when="0">0</span> | 168 <span py:when="0">0</span> |
151 <span py:when="1">1</span> | 169 <span py:when="1">1</span> |
152 <span py:otherwise="">2</span> | 170 <span py:otherwise="">2</span> |
153 </div> | 171 </div> |
154 | 172 |
155 This would produce the following output:: | 173 This would produce the following output: |
174 | |
175 .. code-block:: html | |
156 | 176 |
157 <div> | 177 <div> |
158 <span>1</span> | 178 <span>1</span> |
159 </div> | 179 </div> |
160 | 180 |
165 .. _`py:for`: | 185 .. _`py:for`: |
166 | 186 |
167 ``py:for`` | 187 ``py:for`` |
168 ---------- | 188 ---------- |
169 | 189 |
170 The element is repeated for every item in an iterable:: | 190 The element is repeated for every item in an iterable: |
191 | |
192 .. code-block:: genshi | |
171 | 193 |
172 <ul> | 194 <ul> |
173 <li py:for="item in items">${item}</li> | 195 <li py:for="item in items">${item}</li> |
174 </ul> | 196 </ul> |
175 | 197 |
176 Given ``items=[1, 2, 3]`` in the context data, this would produce:: | 198 Given ``items=[1, 2, 3]`` in the context data, this would produce: |
199 | |
200 .. code-block:: html | |
177 | 201 |
178 <ul> | 202 <ul> |
179 <li>1</li><li>2</li><li>3</li> | 203 <li>1</li><li>2</li><li>3</li> |
180 </ul> | 204 </ul> |
181 | 205 |
182 This directive can also be used as an element:: | 206 This directive can also be used as an element: |
207 | |
208 .. code-block:: genshi | |
183 | 209 |
184 <ul> | 210 <ul> |
185 <py:for each="item in items"> | 211 <py:for each="item in items"> |
186 <li>${item}</li> | 212 <li>${item}</li> |
187 </py:for> | 213 </py:for> |
197 ``py:def`` | 223 ``py:def`` |
198 ---------- | 224 ---------- |
199 | 225 |
200 The ``py:def`` directive can be used to create macros, i.e. snippets of | 226 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 | 227 template code that have a name and optionally some parameters, and that can be |
202 inserted in other places:: | 228 inserted in other places: |
229 | |
230 .. code-block:: genshi | |
203 | 231 |
204 <div> | 232 <div> |
205 <p py:def="greeting(name)" class="greeting"> | 233 <p py:def="greeting(name)" class="greeting"> |
206 Hello, ${name}! | 234 Hello, ${name}! |
207 </p> | 235 </p> |
208 ${greeting('world')} | 236 ${greeting('world')} |
209 ${greeting('everyone else')} | 237 ${greeting('everyone else')} |
210 </div> | 238 </div> |
211 | 239 |
212 The above would be rendered to:: | 240 The above would be rendered to: |
241 | |
242 .. code-block:: html | |
213 | 243 |
214 <div> | 244 <div> |
215 <p class="greeting"> | 245 <p class="greeting"> |
216 Hello, world! | 246 Hello, world! |
217 </p> | 247 </p> |
219 Hello, everyone else! | 249 Hello, everyone else! |
220 </p> | 250 </p> |
221 </div> | 251 </div> |
222 | 252 |
223 If a macro doesn't require parameters, it can be defined without the | 253 If a macro doesn't require parameters, it can be defined without the |
224 parenthesis. For example:: | 254 parenthesis. For example: |
255 | |
256 .. code-block:: genshi | |
225 | 257 |
226 <div> | 258 <div> |
227 <p py:def="greeting" class="greeting"> | 259 <p py:def="greeting" class="greeting"> |
228 Hello, world! | 260 Hello, world! |
229 </p> | 261 </p> |
230 ${greeting()} | 262 ${greeting()} |
231 </div> | 263 </div> |
232 | 264 |
233 The above would be rendered to:: | 265 The above would be rendered to: |
266 | |
267 .. code-block:: html | |
234 | 268 |
235 <div> | 269 <div> |
236 <p class="greeting"> | 270 <p class="greeting"> |
237 Hello, world! | 271 Hello, world! |
238 </p> | 272 </p> |
239 </div> | 273 </div> |
240 | 274 |
241 This directive can also be used as an element:: | 275 This directive can also be used as an element: |
276 | |
277 .. code-block:: genshi | |
242 | 278 |
243 <div> | 279 <div> |
244 <py:def function="greeting(name)"> | 280 <py:def function="greeting(name)"> |
245 <p class="greeting">Hello, ${name}!</p> | 281 <p class="greeting">Hello, ${name}!</p> |
246 </py:def> | 282 </py:def> |
256 This directive defines a *match template*: given an XPath expression, it | 292 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 | 293 replaces any element in the template that matches the expression with its own |
258 content. | 294 content. |
259 | 295 |
260 For example, the match template defined in the following template matches any | 296 For example, the match template defined in the following template matches any |
261 element with the tag name “greeting”:: | 297 element with the tag name “greeting”: |
298 | |
299 .. code-block:: genshi | |
262 | 300 |
263 <div> | 301 <div> |
264 <span py:match="greeting"> | 302 <span py:match="greeting"> |
265 Hello ${select('@name')} | 303 Hello ${select('@name')} |
266 </span> | 304 </span> |
267 <greeting name="Dude" /> | 305 <greeting name="Dude" /> |
268 </div> | 306 </div> |
269 | 307 |
270 This would result in the following output:: | 308 This would result in the following output: |
309 | |
310 .. code-block:: html | |
271 | 311 |
272 <div> | 312 <div> |
273 <span> | 313 <span> |
274 Hello Dude | 314 Hello Dude |
275 </span> | 315 </span> |
280 in the output of the match template. See `Using XPath`_ for more information | 320 in the output of the match template. See `Using XPath`_ for more information |
281 about this function. | 321 about this function. |
282 | 322 |
283 .. _`Using XPath`: streams.html#using-xpath | 323 .. _`Using XPath`: streams.html#using-xpath |
284 | 324 |
285 This directive can also be used as an element:: | 325 This directive can also be used as an element: |
326 | |
327 .. code-block:: genshi | |
286 | 328 |
287 <div> | 329 <div> |
288 <py:match path="greeting"> | 330 <py:match path="greeting"> |
289 <span>Hello ${select('@name')}</span> | 331 <span>Hello ${select('@name')}</span> |
290 </py:match> | 332 </py:match> |
304 be used to make expressions inside the directive less verbose and more | 346 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 | 347 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 | 348 than once, and that actually results in a database query, assigning the results |
307 to a variable using this directive would probably help. | 349 to a variable using this directive would probably help. |
308 | 350 |
309 For example:: | 351 For example: |
352 | |
353 .. code-block:: genshi | |
310 | 354 |
311 <div> | 355 <div> |
312 <span py:with="y=7; z=x+10">$x $y $z</span> | 356 <span py:with="y=7; z=x+10">$x $y $z</span> |
313 </div> | 357 </div> |
314 | 358 |
315 Given ``x=42`` in the context data, this would produce:: | 359 Given ``x=42`` in the context data, this would produce: |
360 | |
361 .. code-block:: html | |
316 | 362 |
317 <div> | 363 <div> |
318 <span>42 7 52</span> | 364 <span>42 7 52</span> |
319 </div> | 365 </div> |
320 | 366 |
321 This directive can also be used as an element:: | 367 This directive can also be used as an element: |
368 | |
369 .. code-block:: genshi | |
322 | 370 |
323 <div> | 371 <div> |
324 <py:with vars="y=7; z=x+10">$x $y $z</py:with> | 372 <py:with vars="y=7; z=x+10">$x $y $z</py:with> |
325 </div> | 373 </div> |
326 | 374 |
336 .. _`py:attrs`: | 384 .. _`py:attrs`: |
337 | 385 |
338 ``py:attrs`` | 386 ``py:attrs`` |
339 ------------ | 387 ------------ |
340 | 388 |
341 This directive adds, modifies or removes attributes from the element:: | 389 This directive adds, modifies or removes attributes from the element: |
390 | |
391 .. code-block:: genshi | |
342 | 392 |
343 <ul> | 393 <ul> |
344 <li py:attrs="foo">Bar</li> | 394 <li py:attrs="foo">Bar</li> |
345 </ul> | 395 </ul> |
346 | 396 |
347 Given ``foo={'class': 'collapse'}`` in the template context, this would | 397 Given ``foo={'class': 'collapse'}`` in the template context, this would |
348 produce:: | 398 produce: |
399 | |
400 .. code-block:: html | |
349 | 401 |
350 <ul> | 402 <ul> |
351 <li class="collapse">Bar</li> | 403 <li class="collapse">Bar</li> |
352 </ul> | 404 </ul> |
353 | 405 |
354 Attributes with the value ``None`` are omitted, so given ``foo={'class': None}`` | 406 Attributes with the value ``None`` are omitted, so given ``foo={'class': None}`` |
355 in the context for the same template this would produce:: | 407 in the context for the same template this would produce: |
408 | |
409 .. code-block:: html | |
356 | 410 |
357 <ul> | 411 <ul> |
358 <li>Bar</li> | 412 <li>Bar</li> |
359 </ul> | 413 </ul> |
360 | 414 |
365 | 419 |
366 ``py:content`` | 420 ``py:content`` |
367 -------------- | 421 -------------- |
368 | 422 |
369 This directive replaces any nested content with the result of evaluating the | 423 This directive replaces any nested content with the result of evaluating the |
370 expression:: | 424 expression: |
425 | |
426 .. code-block:: genshi | |
371 | 427 |
372 <ul> | 428 <ul> |
373 <li py:content="bar">Hello</li> | 429 <li py:content="bar">Hello</li> |
374 </ul> | 430 </ul> |
375 | 431 |
376 Given ``bar='Bye'`` in the context data, this would produce:: | 432 Given ``bar='Bye'`` in the context data, this would produce: |
433 | |
434 .. code-block:: html | |
377 | 435 |
378 <ul> | 436 <ul> |
379 <li>Bye</li> | 437 <li>Bye</li> |
380 </ul> | 438 </ul> |
381 | 439 |
386 | 444 |
387 ``py:replace`` | 445 ``py:replace`` |
388 -------------- | 446 -------------- |
389 | 447 |
390 This directive replaces the element itself with the result of evaluating the | 448 This directive replaces the element itself with the result of evaluating the |
391 expression:: | 449 expression: |
450 | |
451 .. code-block:: genshi | |
392 | 452 |
393 <div> | 453 <div> |
394 <span py:replace="bar">Hello</span> | 454 <span py:replace="bar">Hello</span> |
395 </div> | 455 </div> |
396 | 456 |
397 Given ``bar='Bye'`` in the context data, this would produce:: | 457 Given ``bar='Bye'`` in the context data, this would produce: |
458 | |
459 .. code-block:: html | |
398 | 460 |
399 <div> | 461 <div> |
400 Bye | 462 Bye |
401 </div> | 463 </div> |
402 | 464 |
408 ``py:strip`` | 470 ``py:strip`` |
409 ------------ | 471 ------------ |
410 | 472 |
411 This directive conditionally strips the top-level element from the output. When | 473 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 | 474 the value of the ``py:strip`` attribute evaluates to ``True``, the element is |
413 stripped from the output:: | 475 stripped from the output: |
476 | |
477 .. code-block:: genshi | |
414 | 478 |
415 <div> | 479 <div> |
416 <div py:strip="True"><b>foo</b></div> | 480 <div py:strip="True"><b>foo</b></div> |
417 </div> | 481 </div> |
418 | 482 |
419 This would be rendered as:: | 483 This would be rendered as: |
484 | |
485 .. code-block:: html | |
420 | 486 |
421 <div> | 487 <div> |
422 <b>foo</b> | 488 <b>foo</b> |
423 </div> | 489 </div> |
424 | 490 |
460 | 526 |
461 .. _xinclude: http://www.w3.org/TR/xinclude/ | 527 .. _xinclude: http://www.w3.org/TR/xinclude/ |
462 | 528 |
463 For this, you need to declare the XInclude namespace (commonly bound to the | 529 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 | 530 prefix “xi”) and use the ``<xi:include>`` element where you want the external |
465 file to be pulled in:: | 531 file to be pulled in: |
532 | |
533 .. code-block:: genshi | |
466 | 534 |
467 <html xmlns="http://www.w3.org/1999/xhtml" | 535 <html xmlns="http://www.w3.org/1999/xhtml" |
468 xmlns:py="http://genshi.edgewall.org/" | 536 xmlns:py="http://genshi.edgewall.org/" |
469 xmlns:xi="http://www.w3.org/2001/XInclude"> | 537 xmlns:xi="http://www.w3.org/2001/XInclude"> |
470 <xi:include href="base.html" /> | 538 <xi:include href="base.html" /> |
483 the including template after the point it was included. | 551 the including template after the point it was included. |
484 | 552 |
485 By default, an error will be raised if an included file is not found. If that's | 553 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 | 554 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 | 555 include fails. For example, to to make the include above fail silently, you'd |
488 write:: | 556 write: |
557 | |
558 .. code-block:: genshi | |
489 | 559 |
490 <xi:include href="base.html"><xi:fallback /></xi:include> | 560 <xi:include href="base.html"><xi:fallback /></xi:include> |
491 | 561 |
492 See the `XInclude specification`_ for more about fallback content. Note though | 562 See the `XInclude specification`_ for more about fallback content. Note though |
493 that Genshi currently only supports a small subset of XInclude. | 563 that Genshi currently only supports a small subset of XInclude. |
495 .. _`xinclude specification`: http://www.w3.org/TR/xinclude/ | 565 .. _`xinclude specification`: http://www.w3.org/TR/xinclude/ |
496 | 566 |
497 Incudes in Genshi are fully dynamic: Just like normal attributes, the `href` | 567 Incudes in Genshi are fully dynamic: Just like normal attributes, the `href` |
498 attribute accepts expressions, and directives_ can be used on the | 568 attribute accepts expressions, and directives_ can be used on the |
499 ``<xi:include />`` element just as on any other element, meaning you can do | 569 ``<xi:include />`` element just as on any other element, meaning you can do |
500 things like conditional includes:: | 570 things like conditional includes: |
571 | |
572 .. code-block:: genshi | |
501 | 573 |
502 <xi:include href="${name}.html" py:if="not in_popup" | 574 <xi:include href="${name}.html" py:if="not in_popup" |
503 py:for="name in ('foo', 'bar', 'baz')" /> | 575 py:for="name in ('foo', 'bar', 'baz')" /> |
504 | 576 |
505 | 577 |
507 | 579 |
508 -------- | 580 -------- |
509 Comments | 581 Comments |
510 -------- | 582 -------- |
511 | 583 |
512 Normal XML/HTML comment syntax can be used in templates:: | 584 Normal XML/HTML comment syntax can be used in templates: |
585 | |
586 .. code-block:: genshi | |
513 | 587 |
514 <!-- this is a comment --> | 588 <!-- this is a comment --> |
515 | 589 |
516 However, such comments get passed through the processing pipeline and are by | 590 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 | 591 default included in the final output. If that's not desired, prefix the comment |
518 text with an exclamation mark:: | 592 text with an exclamation mark: |
593 | |
594 .. code-block:: genshi | |
519 | 595 |
520 <!-- !this is a comment too, but one that will be stripped from the output --> | 596 <!-- !this is a comment too, but one that will be stripped from the output --> |
521 | 597 |
522 Note that it does not matter whether there's whitespace before or after the | 598 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:: | 599 exclamation mark, so the above could also be written as follows: |
600 | |
601 .. code-block:: genshi | |
524 | 602 |
525 <!--! this is a comment too, but one that will be stripped from the output --> | 603 <!--! this is a comment too, but one that will be stripped from the output --> |