| 7 | | Markup provides a simple XML-based template language that is heavily inspired |
| 8 | | by Kid_, which in turn was inspired by a number of existing template languages, |
| 9 | | namely XSLT_, TAL_, and PHP_. |
| 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 |
| 18 | | reference to those developing Markup templates. Templates are XML files of some |
| 19 | | kind (such as XHTML) that include processing directives_ (elements or |
| 20 | | attributes identified by a separate namespace) that affect how the template is |
| 21 | | rendered, and template expressions_ that are dynamically substituted by |
| 22 | | variable data. |
| 23 | | |
| 24 | | |
| 25 | | .. contents:: Contents |
| 26 | | :depth: 3 |
| 27 | | .. sectnum:: |
| 28 | | |
| 29 | | ---------- |
| 30 | | Python API |
| 31 | | ---------- |
| 32 | | |
| 33 | | The Python code required for templating with Markup is generally based on the |
| 34 | | following pattern: |
| 35 | | |
| 36 | | * Attain a ``Template`` object from a string or file object containing the |
| 37 | | template XML source. This can either be done directly, or through a |
| 38 | | ``TemplateLoader`` instance. |
| 39 | | * Call the ``generate()`` method of the template, passing any data that should |
| 40 | | be made available to the template as keyword arguments. |
| 41 | | * Serialize the resulting stream using its ``render()`` method. |
| 42 | | |
| 43 | | For example:: |
| 44 | | |
| 45 | | from markup.template import Template |
| 46 | | |
| 47 | | tmpl = Template('<h1>$title</h1>') |
| 48 | | stream = tmpl.generate(title='Hello, world!') |
| 49 | | print stream.render('xhtml') |
| 50 | | |
| 51 | | That code would produce the following output:: |
| 52 | | |
| 53 | | <h1>Hello, world!</h1> |
| 54 | | |
| 55 | | However, if you want includes_ to work, you should attain the template instance |
| 56 | | through a ``TemplateLoader``, and load the template from a file:: |
| 57 | | |
| 58 | | from markup.template import TemplateLoader |
| 59 | | |
| 60 | | loader = TemplateLoader([templates_dir]) |
| 61 | | tmpl = loader.load('test.html') |
| 62 | | stream = tmpl.generate(title='Hello, world!') |
| 63 | | print stream.render('xhtml') |
| 64 | | |
| 65 | | |
| 66 | | .. _`expressions`: |
| 67 | | |
| 68 | | -------------------- |
| 69 | | Template Expressions |
| 70 | | -------------------- |
| 71 | | |
| 72 | | Python_ expressions can be used in text and attribute values. An expression is |
| 73 | | substituted with the result of its evaluation against the template data. |
| 74 | | Expressions need to prefixed with a dollar sign (``$``) and usually enclosed in |
| 75 | | curly braces (``{…}``). |
| 76 | | |
| 77 | | If the expression starts with a letter and contains only letters and digits, |
| 78 | | the curly braces may be omitted. In all other cases, the braces are required so |
| 79 | | that the template processors knows where the expression ends:: |
| 80 | | |
| 81 | | >>> from markup.template import Context, Template |
| 82 | | >>> tmpl = Template('<em>${items[0].capitalize()} item</em>') |
| 83 | | >>> print tmpl.generate(Context(items=['first', 'second'])) |
| 84 | | <em>First item</em> |
| 85 | | |
| 86 | | Expressions support the full power of Python. In addition, it is possible to |
| 87 | | access items in a dictionary using “dotted notation” (i.e. as if they were |
| 88 | | attributes), and vice-versa (i.e. access attributes as if they were items in a |
| 89 | | dictionary):: |
| 90 | | |
| 91 | | >>> from markup.template import Context, Template |
| 92 | | >>> tmpl = Template('<em>${dict.foo}</em>') |
| 93 | | >>> print tmpl.generate(Context(dict={'foo': 'bar'})) |
| 94 | | <em>bar</em> |
| 95 | | |
| 96 | | |
| 97 | | .. _`directives`: |
| 98 | | |
| 99 | | ------------------- |
| 100 | | Template Directives |
| 101 | | ------------------- |
| 102 | | |
| 103 | | Directives are elements and/or attributes in the template that are identified |
| 104 | | by the namespace ``http://markup.edgewall.org/``. They can affect how the |
| 105 | | template is rendered in a number of ways: Markup provides directives for |
| 106 | | conditionals and looping, among others. |
| 107 | | |
| 108 | | To use directives in a template, the namespace should be declared, which is |
| 109 | | usually done on the root element:: |
| 110 | | |
| 111 | | <html xmlns="http://www.w3.org/1999/xhtml" |
| 112 | | xmlns:py="http://markup.edgewall.org/" |
| 113 | | lang="en"> |
| 114 | | ... |
| 115 | | </html> |
| 116 | | |
| 117 | | In this example, the default namespace is set to the XHTML namespace, and the |
| 118 | | namespace for Markup directives is bound to the prefix “py”. |
| 119 | | |
| 120 | | All directives can be applied as attributes, and some can also be used as |
| 121 | | elements. The ``if`` directives for conditionals, for example, can be used in |
| 122 | | both ways:: |
| 123 | | |
| 124 | | <html xmlns="http://www.w3.org/1999/xhtml" |
| 125 | | xmlns:py="http://markup.edgewall.org/" |
| 126 | | lang="en"> |
| 127 | | ... |
| 128 | | <div py:if="foo"> |
| 129 | | <p>Bar</p> |
| 130 | | </div> |
| 131 | | ... |
| 132 | | </html> |
| 133 | | |
| 134 | | This is basically equivalent to the following:: |
| 135 | | |
| 136 | | <html xmlns="http://www.w3.org/1999/xhtml" |
| 137 | | xmlns:py="http://markup.edgewall.org/" |
| 138 | | lang="en"> |
| 139 | | ... |
| 140 | | <py:if test="foo"> |
| 141 | | <div> |
| 142 | | <p>Bar</p> |
| 143 | | </div> |
| 144 | | </py:if> |
| 145 | | ... |
| 146 | | </html> |
| 147 | | |
| 148 | | The rationale behind the second form is that directives do not always map |
| 149 | | naturally to elements in the template. In such cases, the ``py:strip`` |
| 150 | | directive can be used to strip off the unwanted element, or the directive can |
| 151 | | simply be used as an element. |
| 152 | | |
| 153 | | |
| 154 | | Available Directives |
| 155 | | ==================== |
| 156 | | |
| 157 | | |
| 158 | | .. _`py:attrs`: |
| 159 | | |
| 160 | | ``py:attrs`` |
| 161 | | ------------ |
| 162 | | |
| 163 | | This directive adds, modifies or removes attributes from the element:: |
| 164 | | |
| 165 | | <ul> |
| 166 | | <li py:attrs="foo">Bar</li> |
| 167 | | </ul> |
| 168 | | |
| 169 | | Given ``foo={'class': 'collapse'}`` in the template context, this would |
| 170 | | produce:: |
| 171 | | |
| 172 | | <ul> |
| 173 | | <li class="collapse">Bar</li> |
| 174 | | </ul> |
| 175 | | |
| 176 | | Attributes with the value ``None`` are omitted, so given ``foo={'class': None}`` |
| 177 | | in the context for the same template this would produce:: |
| 178 | | |
| 179 | | <ul> |
| 180 | | <li>Bar</li> |
| 181 | | </ul> |
| 182 | | |
| 183 | | This directive can only be used as an attribute. |
| 184 | | |
| 185 | | |
| 186 | | .. _`py:choose`: |
| 187 | | .. _`py:when`: |
| 188 | | .. _`py:otherwise`: |
| 189 | | |
| 190 | | ``py:choose`` / ``py:when`` / ``py:otherwise`` |
| 191 | | ---------------------------------------------- |
| 192 | | |
| 193 | | This set of directives provides advanced contional processing for rendering one |
| 194 | | of several alternatives. The first matching ``py:when`` branch is rendered, or, |
| 195 | | if no ``py:when`` branch matches, the ``py:otherwise`` branch is be rendered. |
| 196 | | |
| 197 | | If the ``py:choose`` directive is empty the nested ``py:when`` directives will |
| 198 | | be tested for truth:: |
| 199 | | |
| 200 | | <div py:choose=""> |
| 201 | | <span py:when="0 == 1">0</span> |
| 202 | | <span py:when="1 == 1">1</span> |
| 203 | | <span py:otherwise="">2</span> |
| 204 | | </div> |
| 205 | | |
| 206 | | This would produce the following output:: |
| 207 | | |
| 208 | | <div> |
| 209 | | <span>1</span> |
| 210 | | </div> |
| 211 | | |
| 212 | | If the ``py:choose`` directive contains an expression the nested ``py:when`` |
| 213 | | directives will be tested for equality to the parent ``py:choose`` value:: |
| 214 | | |
| 215 | | <div py:choose="1"> |
| 216 | | <span py:when="0">0</span> |
| 217 | | <span py:when="1">1</span> |
| 218 | | <span py:otherwise="">2</span> |
| 219 | | </div> |
| 220 | | |
| 221 | | This would produce the following output:: |
| 222 | | |
| 223 | | <div> |
| 224 | | <span>1</span> |
| 225 | | </div> |
| 226 | | |
| 227 | | |
| 228 | | .. _`py:content`: |
| 229 | | |
| 230 | | ``py:content`` |
| 231 | | -------------- |
| 232 | | |
| 233 | | This directive replaces any nested content with the result of evaluating the |
| 234 | | expression:: |
| 235 | | |
| 236 | | <ul> |
| 237 | | <li py:content="bar">Hello</li> |
| 238 | | </ul> |
| 239 | | |
| 240 | | Given ``bar='Bye'`` in the context data, this would produce:: |
| 241 | | |
| 242 | | <ul> |
| 243 | | <li>Bye</li> |
| 244 | | </ul> |
| 245 | | |
| 246 | | This directive can only be used as an attribute. |
| 247 | | |
| 248 | | |
| 249 | | .. _`py:def`: |
| 250 | | .. _`macros`: |
| 251 | | |
| 252 | | ``py:def`` |
| 253 | | ---------- |
| 254 | | |
| 255 | | The ``py:def`` directive can be used to create macros, i.e. snippets of |
| 256 | | template code that have a name and optionally some parameters, and that can be |
| 257 | | inserted in other places:: |
| 258 | | |
| 259 | | <div> |
| 260 | | <p py:def="greeting(name)" class="greeting"> |
| 261 | | Hello, ${name}! |
| 262 | | </p> |
| 263 | | ${greeting('world')} |
| 264 | | ${greeting('everyone else')} |
| 265 | | </div> |
| 266 | | |
| 267 | | The above would be rendered to:: |
| 268 | | |
| 269 | | <div> |
| 270 | | <p class="greeting"> |
| 271 | | Hello, world! |
| 272 | | </p> |
| 273 | | <p class="greeting"> |
| 274 | | Hello, everyone else! |
| 275 | | </p> |
| 276 | | </div> |
| 277 | | |
| 278 | | If a macro doesn't require parameters, it can be defined as well as called |
| 279 | | without the parenthesis. For example:: |
| 280 | | |
| 281 | | <div> |
| 282 | | <p py:def="greeting" class="greeting"> |
| 283 | | Hello, world! |
| 284 | | </p> |
| 285 | | ${greeting} |
| 286 | | </div> |
| 287 | | |
| 288 | | The above would be rendered to:: |
| 289 | | |
| 290 | | <div> |
| 291 | | <p class="greeting"> |
| 292 | | Hello, world! |
| 293 | | </p> |
| 294 | | </div> |
| 295 | | |
| 296 | | This directive can also be used as an element:: |
| 297 | | |
| 298 | | <div> |
| 299 | | <py:def function="greeting(name)"> |
| 300 | | <p class="greeting">Hello, ${name}!</p> |
| 301 | | </py:def> |
| 302 | | </div> |
| 303 | | |
| 304 | | |
| 305 | | .. _`py:for`: |
| 306 | | |
| 307 | | ``py:for`` |
| 308 | | ---------- |
| 309 | | |
| 310 | | The element is repeated for every item in an iterable:: |
| 311 | | |
| 312 | | <ul> |
| 313 | | <li py:for="item in items">${item}</li> |
| 314 | | </ul> |
| 315 | | |
| 316 | | Given ``items=[1, 2, 3]`` in the context data, this would produce:: |
| 317 | | |
| 318 | | <ul> |
| 319 | | <li>1</li><li>2</li><li>3</li> |
| 320 | | </ul> |
| 321 | | |
| 322 | | This directive can also be used as an element:: |
| 323 | | |
| 324 | | <ul> |
| 325 | | <py:for each="item in items"> |
| 326 | | <li>${item}</li> |
| 327 | | </py:for> |
| 328 | | </ul> |
| 329 | | |
| 330 | | |
| 331 | | .. _`py:if`: |
| 332 | | |
| 333 | | ``py:if`` |
| 334 | | ------------ |
| 335 | | |
| 336 | | The element is only rendered if the expression evaluates to a truth value:: |
| 337 | | |
| 338 | | <div> |
| 339 | | <b py:if="foo">${bar}</b> |
| 340 | | </div> |
| 341 | | |
| 342 | | Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this |
| 343 | | would produce:: |
| 344 | | |
| 345 | | <div> |
| 346 | | <b>Hello</b> |
| 347 | | </div> |
| 348 | | |
| 349 | | This directive can also be used as an element:: |
| 350 | | |
| 351 | | <div> |
| 352 | | <py:if test="foo"> |
| 353 | | <b>${bar}</b> |
| 354 | | </py:if> |
| 355 | | </div> |
| 356 | | |
| 357 | | |
| 358 | | .. _`py:match`: |
| 359 | | .. _Match Templates: |
| 360 | | |
| 361 | | ``py:match`` |
| 362 | | ------------ |
| 363 | | |
| 364 | | This directive defines a *match template*: given an XPath expression, it |
| 365 | | replaces any element in the template that matches the expression with its own |
| 366 | | content. |
| 367 | | |
| 368 | | For example, the match template defined in the following template matches any |
| 369 | | element with the tag name “greeting”:: |
| 370 | | |
| 371 | | <div> |
| 372 | | <span py:match="greeting"> |
| 373 | | Hello ${select('@name')} |
| 374 | | </span> |
| 375 | | <greeting name="Dude" /> |
| 376 | | </div> |
| 377 | | |
| 378 | | This would result in the following output:: |
| 379 | | |
| 380 | | <div> |
| 381 | | <span> |
| 382 | | Hello Dude |
| 383 | | </span> |
| 384 | | </div> |
| 385 | | |
| 386 | | Inside the body of a ``py:match`` directive, the ``select(path)`` function is |
| 387 | | made available so that parts or all of the original element can be incorporated |
| 388 | | in the output of the match template. See [wiki:MarkupStream#UsingXPath] for |
| 389 | | more information about this function. |
| 390 | | |
| 391 | | This directive can also be used as an element:: |
| 392 | | |
| 393 | | <div> |
| 394 | | <py:match path="greeting"> |
| 395 | | <span>Hello ${select('@name')}</span> |
| 396 | | </py:match> |
| 397 | | <greeting name="Dude" /> |
| 398 | | </div> |
| 399 | | |
| 400 | | |
| 401 | | .. _`py:replace`: |
| 402 | | |
| 403 | | ``py:replace`` |
| 404 | | -------------- |
| 405 | | |
| 406 | | This directive replaces the element itself with the result of evaluating the |
| 407 | | expression:: |
| 408 | | |
| 409 | | <div> |
| 410 | | <span py:replace="bar">Hello</span> |
| 411 | | </div> |
| 412 | | |
| 413 | | Given ``bar='Bye'`` in the context data, this would produce:: |
| 414 | | |
| 415 | | <div> |
| 416 | | Bye |
| 417 | | </div> |
| 418 | | |
| 419 | | This directive can only be used as an attribute. |
| 420 | | |
| 421 | | |
| 422 | | .. _`py:strip`: |
| 423 | | |
| 424 | | ``py:strip`` |
| 425 | | ------------ |
| 426 | | |
| 427 | | This directive conditionally strips the top-level element from the output. When |
| 428 | | the value of the ``py:strip`` attribute evaluates to ``True``, the element is |
| 429 | | stripped from the output:: |
| 430 | | |
| 431 | | <div> |
| 432 | | <div py:strip="True"><b>foo</b></div> |
| 433 | | </div> |
| 434 | | |
| 435 | | This would be rendered as:: |
| 436 | | |
| 437 | | <div> |
| 438 | | <b>foo</b> |
| 439 | | </div> |
| 440 | | |
| 441 | | As a shorthand, if the value of the ``py:strip`` attribute is empty, that has |
| 442 | | the same effect as using a truth value (i.e. the element is stripped). |
| 443 | | |
| 444 | | |
| 445 | | .. _`with`: |
| 446 | | |
| 447 | | ``py:with`` |
| 448 | | ----------- |
| 449 | | |
| 450 | | The ``py:with`` directive lets you assign expressions to variables, which can |
| 451 | | be used to make expressions inside the directive less verbose and more |
| 452 | | efficient. For example, if you need use the expression ``author.posts`` more |
| 453 | | than once, and that actually results in a database query, assigning the results |
| 454 | | to a variable using this directive would probably help. |
| 455 | | |
| 456 | | For example:: |
| 457 | | |
| 458 | | <div> |
| 459 | | <span py:with="y=7; z=x+10">$x $y $z</span> |
| 460 | | </div> |
| 461 | | |
| 462 | | Given ``x=42`` in the context data, this would produce:: |
| 463 | | |
| 464 | | <div> |
| 465 | | <span>42 7 52</span> |
| 466 | | </div> |
| 467 | | |
| 468 | | This directive can also be used as an element:: |
| 469 | | |
| 470 | | <div> |
| 471 | | <py:with vars="y=7; z=x+10">$x $y $z</py:with> |
| 472 | | </div> |
| 473 | | |
| 474 | | Note that if a variable of the same name already existed outside of the scope |
| 475 | | of the ``py:with`` directive, it will **not** be overwritten. Instead, it |
| 476 | | will have the same value it had prior to the ``py:with`` assignment. |
| 477 | | Effectively, this means that variables are immutable in Markup. |
| 478 | | |
| 479 | | |
| 480 | | .. _order: |
| 481 | | |
| 482 | | Processing Order |
| 483 | | ================ |
| 484 | | |
| 485 | | It is possible to attach multiple directives to a single element, although not |
| 486 | | all combinations make sense. When multiple directives are encountered, they are |
| 487 | | processed in the following order: |
| 488 | | |
| 489 | | #. `py:def`_ |
| 490 | | #. `py:match`_ |
| 491 | | #. `py:when`_ |
| 492 | | #. `py:otherwise`_ |
| 493 | | #. `py:for`_ |
| 494 | | #. `py:if`_ |
| 495 | | #. `py:choose`_ |
| 496 | | #. `py:with`_ |
| 497 | | #. `py:replace`_ |
| 498 | | #. `py:content`_ |
| 499 | | #. `py:attrs`_ |
| 500 | | #. `py:strip`_ |
| 501 | | |
| 502 | | |
| 503 | | .. _includes: |
| 504 | | |
| 505 | | -------- |
| 506 | | Includes |
| 507 | | -------- |
| 508 | | |
| 509 | | To reuse common snippets of template code, you can include other files using |
| 510 | | XInclude_. |
| 511 | | |
| 512 | | .. _xinclude: http://www.w3.org/TR/xinclude/ |
| 513 | | |
| 514 | | For this, you need to declare the XInclude namespace (commonly bound to the |
| 515 | | prefix “xi”) and use the ``<xi:include>`` element where you want the external |
| 516 | | file to be pulled in:: |
| 517 | | |
| 518 | | <html xmlns="http://www.w3.org/1999/xhtml" |
| 519 | | xmlns:py="http://markup.edgewall.org/" |
| 520 | | xmlns:xi="http://www.w3.org/2001/XInclude"> |
| 521 | | <xi:include href="base.html" /> |
| 522 | | ... |
| 523 | | </html> |
| 524 | | |
| 525 | | Include paths are relative to the filename of the template currently being |
| 526 | | processed. So if the example above was in the file "``myapp/index.html``" |
| 527 | | (relative to the template search path), the XInclude processor would look for |
| 528 | | the included file at "``myapp/base.html``". You can also use Unix-style |
| 529 | | relative paths, for example "``../base.html``" to look in the parent directory. |
| 530 | | |
| 531 | | Any content included this way is inserted into the generated output instead of |
| 532 | | the ``<xi:include>`` element. The included template sees the same context data. |
| 533 | | `Match templates`_ and `macros`_ in the included template are also available to |
| 534 | | the including template after the point it was included. |
| 535 | | |
| 536 | | By default, an error will be raised if an included file is not found. If that's |
| 537 | | not what you want, you can specify fallback content that should be used if the |
| 538 | | include fails. For example, to to make the include above fail silently, you'd |
| 539 | | write: |
| 540 | | |
| 541 | | <xi:include href="base.html"><xi:fallback /></xi:include> |
| 542 | | |
| 543 | | See the XInclude_ for more about fallback content. Note though that Markup |
| 544 | | currently only supports a small subset of XInclude. |
| 545 | | |
| 546 | | Incudes in Markup are fully dynamic: Just like normal attributes, the `href` |
| 547 | | attribute accepts expressions_, and directives_ can be used on the |
| 548 | | ``<xi:include />`` element just as on any other element, meaning you can do |
| 549 | | things like conditional includes:: |
| 550 | | |
| 551 | | <xi:include href="${name}.html" py:if="not in_popup" |
| 552 | | py:for="name in ('foo', 'bar', 'baz')" /> |
| 553 | | |
| 554 | | |
| 555 | | .. _comments: |
| 556 | | |
| 557 | | -------- |
| 558 | | Comments |
| 559 | | -------- |
| 560 | | |
| 561 | | Normal XML/HTML comment syntax can be used in templates:: |
| 562 | | |
| 563 | | <!-- this is a comment --> |
| 564 | | |
| 565 | | However, such comments get passed through the processing pipeline and are by |
| 566 | | default included in the final output. If that's not desired, prefix the comment |
| 567 | | text with an exclamation mark:: |
| 568 | | |
| 569 | | <!-- !this is a comment too, but one that will be stripped from the output --> |
| 570 | | |
| 571 | | Note that it does not matter whether there's whitespace before or after the |
| 572 | | exclamation mark, so the above could also be written as follows:: |
| 573 | | |
| 574 | | <!--! this is a comment too, but one that will be stripped from the output --> |
| 575 | | }}} |
