Mercurial > genshi > mirror
annotate doc/xml-templates.txt @ 490:540aff78a5a0 stable-0.4.x 0.4.1
Ported [589] to 0.4.x.
| author | cmlenz |
|---|---|
| date | Mon, 21 May 2007 09:22:25 +0000 |
| parents | 4183fd29fa4e |
| children | 1bdccd3bda00 |
| 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 |
| 226 | 45 usually done on the root element:: |
| 46 | |
| 47 <html xmlns="http://www.w3.org/1999/xhtml" | |
| 230 | 48 xmlns:py="http://genshi.edgewall.org/" |
| 226 | 49 lang="en"> |
| 50 ... | |
| 51 </html> | |
| 52 | |
| 53 In this example, the default namespace is set to the XHTML namespace, and the | |
| 230 | 54 namespace for Genshi directives is bound to the prefix “py”. |
| 226 | 55 |
| 56 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 | |
| 58 both ways:: | |
| 59 | |
| 60 <html xmlns="http://www.w3.org/1999/xhtml" | |
| 230 | 61 xmlns:py="http://genshi.edgewall.org/" |
| 226 | 62 lang="en"> |
| 63 ... | |
| 64 <div py:if="foo"> | |
| 65 <p>Bar</p> | |
| 66 </div> | |
| 67 ... | |
| 68 </html> | |
| 69 | |
| 70 This is basically equivalent to the following:: | |
| 71 | |
| 72 <html xmlns="http://www.w3.org/1999/xhtml" | |
| 230 | 73 xmlns:py="http://genshi.edgewall.org/" |
| 226 | 74 lang="en"> |
| 75 ... | |
| 76 <py:if test="foo"> | |
| 77 <div> | |
| 78 <p>Bar</p> | |
| 79 </div> | |
| 80 </py:if> | |
| 81 ... | |
| 82 </html> | |
| 83 | |
| 84 The rationale behind the second form is that directives do not always map | |
| 85 naturally to elements in the template. In such cases, the ``py:strip`` | |
| 86 directive can be used to strip off the unwanted element, or the directive can | |
| 87 simply be used as an element. | |
| 88 | |
| 89 | |
| 237 | 90 Conditional Sections |
| 226 | 91 ==================== |
| 92 | |
| 235 | 93 .. _`py:if`: |
| 226 | 94 |
| 235 | 95 ``py:if`` |
| 237 | 96 --------- |
| 226 | 97 |
| 235 | 98 The element is only rendered if the expression evaluates to a truth value:: |
| 226 | 99 |
| 235 | 100 <div> |
| 101 <b py:if="foo">${bar}</b> | |
| 102 </div> | |
| 226 | 103 |
| 235 | 104 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this |
| 105 would produce:: | |
| 106 | |
| 107 <div> | |
| 108 <b>Hello</b> | |
| 109 </div> | |
| 110 | |
| 111 This directive can also be used as an element:: | |
| 112 | |
| 113 <div> | |
| 114 <py:if test="foo"> | |
| 115 <b>${bar}</b> | |
| 116 </py:if> | |
| 117 </div> | |
| 226 | 118 |
| 119 .. _`py:choose`: | |
| 120 .. _`py:when`: | |
| 121 .. _`py:otherwise`: | |
| 122 | |
| 237 | 123 ``py:choose`` |
| 124 ------------- | |
| 226 | 125 |
| 237 | 126 The ``py:choose`` directive, in combination with the directives ``py:when`` |
| 404 | 127 and ``py:otherwise`` provides advanced conditional processing for rendering one |
| 226 | 128 of several alternatives. The first matching ``py:when`` branch is rendered, or, |
| 404 | 129 if no ``py:when`` branch matches, the ``py:otherwise`` branch is rendered. |
| 226 | 130 |
| 131 If the ``py:choose`` directive is empty the nested ``py:when`` directives will | |
| 132 be tested for truth:: | |
| 133 | |
| 134 <div py:choose=""> | |
| 135 <span py:when="0 == 1">0</span> | |
| 136 <span py:when="1 == 1">1</span> | |
| 137 <span py:otherwise="">2</span> | |
| 138 </div> | |
| 139 | |
| 140 This would produce the following output:: | |
| 141 | |
| 142 <div> | |
| 143 <span>1</span> | |
| 144 </div> | |
| 145 | |
| 146 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:: | |
| 148 | |
| 149 <div py:choose="1"> | |
| 150 <span py:when="0">0</span> | |
| 151 <span py:when="1">1</span> | |
| 152 <span py:otherwise="">2</span> | |
| 153 </div> | |
| 154 | |
| 155 This would produce the following output:: | |
| 156 | |
| 157 <div> | |
| 158 <span>1</span> | |
| 159 </div> | |
| 160 | |
| 161 | |
| 235 | 162 Looping |
| 237 | 163 ======= |
| 226 | 164 |
| 235 | 165 .. _`py:for`: |
| 226 | 166 |
| 235 | 167 ``py:for`` |
| 237 | 168 ---------- |
| 235 | 169 |
| 170 The element is repeated for every item in an iterable:: | |
| 226 | 171 |
| 172 <ul> | |
| 235 | 173 <li py:for="item in items">${item}</li> |
| 226 | 174 </ul> |
| 175 | |
| 235 | 176 Given ``items=[1, 2, 3]`` in the context data, this would produce:: |
| 226 | 177 |
| 178 <ul> | |
| 235 | 179 <li>1</li><li>2</li><li>3</li> |
| 226 | 180 </ul> |
| 181 | |
| 235 | 182 This directive can also be used as an element:: |
| 226 | 183 |
| 235 | 184 <ul> |
| 185 <py:for each="item in items"> | |
| 186 <li>${item}</li> | |
| 187 </py:for> | |
| 188 </ul> | |
| 189 | |
| 190 | |
| 191 Snippet Reuse | |
| 237 | 192 ============= |
| 226 | 193 |
| 194 .. _`py:def`: | |
| 195 .. _`macros`: | |
| 196 | |
| 197 ``py:def`` | |
| 237 | 198 ---------- |
| 226 | 199 |
| 200 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 | |
| 202 inserted in other places:: | |
| 203 | |
| 204 <div> | |
| 205 <p py:def="greeting(name)" class="greeting"> | |
| 206 Hello, ${name}! | |
| 207 </p> | |
| 208 ${greeting('world')} | |
| 209 ${greeting('everyone else')} | |
| 210 </div> | |
| 211 | |
| 212 The above would be rendered to:: | |
| 213 | |
| 214 <div> | |
| 215 <p class="greeting"> | |
| 216 Hello, world! | |
| 217 </p> | |
| 218 <p class="greeting"> | |
| 219 Hello, everyone else! | |
| 220 </p> | |
| 221 </div> | |
| 222 | |
| 394 | 223 If a macro doesn't require parameters, it can be defined without the |
| 224 parenthesis. For example:: | |
| 226 | 225 |
| 226 <div> | |
| 227 <p py:def="greeting" class="greeting"> | |
| 228 Hello, world! | |
| 229 </p> | |
| 394 | 230 ${greeting()} |
| 226 | 231 </div> |
| 232 | |
| 233 The above would be rendered to:: | |
| 234 | |
| 235 <div> | |
| 236 <p class="greeting"> | |
| 237 Hello, world! | |
| 238 </p> | |
| 239 </div> | |
| 240 | |
| 241 This directive can also be used as an element:: | |
| 242 | |
| 243 <div> | |
| 244 <py:def function="greeting(name)"> | |
| 245 <p class="greeting">Hello, ${name}!</p> | |
| 246 </py:def> | |
| 247 </div> | |
| 248 | |
| 249 | |
| 235 | 250 .. _Match Templates: |
| 226 | 251 .. _`py:match`: |
| 252 | |
| 253 ``py:match`` | |
| 237 | 254 ------------ |
| 226 | 255 |
| 256 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 | |
| 258 content. | |
| 259 | |
| 260 For example, the match template defined in the following template matches any | |
| 261 element with the tag name “greeting”:: | |
| 262 | |
| 263 <div> | |
| 264 <span py:match="greeting"> | |
| 265 Hello ${select('@name')} | |
| 266 </span> | |
| 267 <greeting name="Dude" /> | |
| 268 </div> | |
| 269 | |
| 270 This would result in the following output:: | |
| 271 | |
| 272 <div> | |
| 273 <span> | |
| 274 Hello Dude | |
| 275 </span> | |
| 276 </div> | |
| 277 | |
| 278 Inside the body of a ``py:match`` directive, the ``select(path)`` function is | |
| 279 made available so that parts or all of the original element can be incorporated | |
| 451 | 280 in the output of the match template. See `Using XPath`_ for more information |
| 281 about this function. | |
| 282 | |
| 283 .. _`Using XPath`: streams.html#using-xpath | |
| 226 | 284 |
| 285 This directive can also be used as an element:: | |
| 286 | |
| 287 <div> | |
| 288 <py:match path="greeting"> | |
| 289 <span>Hello ${select('@name')}</span> | |
| 290 </py:match> | |
| 291 <greeting name="Dude" /> | |
| 292 </div> | |
| 293 | |
| 294 | |
| 235 | 295 Variable Binding |
| 237 | 296 ================ |
| 226 | 297 |
| 298 .. _`with`: | |
| 299 | |
| 300 ``py:with`` | |
| 237 | 301 ----------- |
| 226 | 302 |
| 303 The ``py:with`` directive lets you assign expressions to variables, which can | |
| 304 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 | |
| 306 than once, and that actually results in a database query, assigning the results | |
| 307 to a variable using this directive would probably help. | |
| 308 | |
| 309 For example:: | |
| 310 | |
| 311 <div> | |
| 312 <span py:with="y=7; z=x+10">$x $y $z</span> | |
| 313 </div> | |
| 314 | |
| 315 Given ``x=42`` in the context data, this would produce:: | |
| 316 | |
| 317 <div> | |
| 318 <span>42 7 52</span> | |
| 319 </div> | |
| 320 | |
| 321 This directive can also be used as an element:: | |
| 322 | |
| 323 <div> | |
| 324 <py:with vars="y=7; z=x+10">$x $y $z</py:with> | |
| 325 </div> | |
| 326 | |
| 327 Note that if a variable of the same name already existed outside of the scope | |
| 328 of the ``py:with`` directive, it will **not** be overwritten. Instead, it | |
| 329 will have the same value it had prior to the ``py:with`` assignment. | |
| 230 | 330 Effectively, this means that variables are immutable in Genshi. |
| 226 | 331 |
| 332 | |
| 235 | 333 Structure Manipulation |
| 237 | 334 ====================== |
| 235 | 335 |
| 336 .. _`py:attrs`: | |
| 337 | |
| 338 ``py:attrs`` | |
| 237 | 339 ------------ |
| 235 | 340 |
| 341 This directive adds, modifies or removes attributes from the element:: | |
| 342 | |
| 343 <ul> | |
| 344 <li py:attrs="foo">Bar</li> | |
| 345 </ul> | |
| 346 | |
| 347 Given ``foo={'class': 'collapse'}`` in the template context, this would | |
| 348 produce:: | |
| 349 | |
| 350 <ul> | |
| 351 <li class="collapse">Bar</li> | |
| 352 </ul> | |
| 353 | |
| 354 Attributes with the value ``None`` are omitted, so given ``foo={'class': None}`` | |
| 355 in the context for the same template this would produce:: | |
| 356 | |
| 357 <ul> | |
| 358 <li>Bar</li> | |
| 359 </ul> | |
| 360 | |
| 361 This directive can only be used as an attribute. | |
| 362 | |
| 363 | |
| 364 .. _`py:content`: | |
| 365 | |
| 366 ``py:content`` | |
| 237 | 367 -------------- |
| 235 | 368 |
| 369 This directive replaces any nested content with the result of evaluating the | |
| 370 expression:: | |
| 371 | |
| 372 <ul> | |
| 373 <li py:content="bar">Hello</li> | |
| 374 </ul> | |
| 375 | |
| 376 Given ``bar='Bye'`` in the context data, this would produce:: | |
| 377 | |
| 378 <ul> | |
| 379 <li>Bye</li> | |
| 380 </ul> | |
| 381 | |
| 382 This directive can only be used as an attribute. | |
| 383 | |
| 384 | |
| 385 .. _`py:replace`: | |
| 386 | |
| 387 ``py:replace`` | |
| 237 | 388 -------------- |
| 235 | 389 |
| 390 This directive replaces the element itself with the result of evaluating the | |
| 391 expression:: | |
| 392 | |
| 393 <div> | |
| 394 <span py:replace="bar">Hello</span> | |
| 395 </div> | |
| 396 | |
| 397 Given ``bar='Bye'`` in the context data, this would produce:: | |
| 398 | |
| 399 <div> | |
| 400 Bye | |
| 401 </div> | |
| 402 | |
| 403 This directive can only be used as an attribute. | |
| 404 | |
| 405 | |
| 406 .. _`py:strip`: | |
| 407 | |
| 408 ``py:strip`` | |
| 237 | 409 ------------ |
| 235 | 410 |
| 411 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 | |
| 413 stripped from the output:: | |
| 414 | |
| 415 <div> | |
| 416 <div py:strip="True"><b>foo</b></div> | |
| 417 </div> | |
| 418 | |
| 419 This would be rendered as:: | |
| 420 | |
| 421 <div> | |
| 422 <b>foo</b> | |
| 423 </div> | |
| 424 | |
| 425 As a shorthand, if the value of the ``py:strip`` attribute is empty, that has | |
| 426 the same effect as using a truth value (i.e. the element is stripped). | |
| 427 | |
| 428 | |
| 226 | 429 .. _order: |
| 430 | |
| 431 Processing Order | |
| 432 ================ | |
| 433 | |
| 434 It is possible to attach multiple directives to a single element, although not | |
| 435 all combinations make sense. When multiple directives are encountered, they are | |
| 436 processed in the following order: | |
| 437 | |
| 438 #. `py:def`_ | |
| 439 #. `py:match`_ | |
| 440 #. `py:when`_ | |
| 441 #. `py:otherwise`_ | |
| 442 #. `py:for`_ | |
| 443 #. `py:if`_ | |
| 444 #. `py:choose`_ | |
| 445 #. `py:with`_ | |
| 446 #. `py:replace`_ | |
| 447 #. `py:content`_ | |
| 448 #. `py:attrs`_ | |
| 449 #. `py:strip`_ | |
| 450 | |
| 451 | |
| 452 .. _includes: | |
| 453 | |
| 454 -------- | |
| 455 Includes | |
| 456 -------- | |
| 457 | |
| 458 To reuse common snippets of template code, you can include other files using | |
| 459 XInclude_. | |
| 460 | |
| 461 .. _xinclude: http://www.w3.org/TR/xinclude/ | |
| 462 | |
| 463 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 | |
| 465 file to be pulled in:: | |
| 466 | |
| 467 <html xmlns="http://www.w3.org/1999/xhtml" | |
| 230 | 468 xmlns:py="http://genshi.edgewall.org/" |
| 226 | 469 xmlns:xi="http://www.w3.org/2001/XInclude"> |
| 470 <xi:include href="base.html" /> | |
| 471 ... | |
| 472 </html> | |
| 473 | |
| 474 Include paths are relative to the filename of the template currently being | |
| 475 processed. So if the example above was in the file "``myapp/index.html``" | |
| 476 (relative to the template search path), the XInclude processor would look for | |
| 477 the included file at "``myapp/base.html``". You can also use Unix-style | |
| 478 relative paths, for example "``../base.html``" to look in the parent directory. | |
| 479 | |
| 480 Any content included this way is inserted into the generated output instead of | |
| 481 the ``<xi:include>`` element. The included template sees the same context data. | |
| 482 `Match templates`_ and `macros`_ in the included template are also available to | |
| 483 the including template after the point it was included. | |
| 484 | |
| 485 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 | |
| 487 include fails. For example, to to make the include above fail silently, you'd | |
| 273 | 488 write:: |
| 226 | 489 |
| 490 <xi:include href="base.html"><xi:fallback /></xi:include> | |
| 491 | |
| 273 | 492 See the `XInclude specification`_ for more about fallback content. Note though |
| 493 that Genshi currently only supports a small subset of XInclude. | |
| 494 | |
| 495 .. _`xinclude specification`: http://www.w3.org/TR/xinclude/ | |
| 226 | 496 |
| 230 | 497 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
|
498 attribute accepts expressions, and directives_ can be used on the |
| 226 | 499 ``<xi:include />`` element just as on any other element, meaning you can do |
| 500 things like conditional includes:: | |
| 501 | |
| 502 <xi:include href="${name}.html" py:if="not in_popup" | |
| 503 py:for="name in ('foo', 'bar', 'baz')" /> | |
| 504 | |
| 505 | |
| 506 .. _comments: | |
| 507 | |
| 508 -------- | |
| 509 Comments | |
| 510 -------- | |
| 511 | |
| 512 Normal XML/HTML comment syntax can be used in templates:: | |
| 513 | |
| 514 <!-- this is a comment --> | |
| 515 | |
| 516 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 | |
| 518 text with an exclamation mark:: | |
| 519 | |
| 520 <!-- !this is a comment too, but one that will be stripped from the output --> | |
| 521 | |
| 522 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:: | |
| 524 | |
| 525 <!--! this is a comment too, but one that will be stripped from the output --> |