Mercurial > genshi > mirror
annotate doc/xml-templates.txt @ 636:699601cce3cc trunk
Follow-up to [751]: applying the optimization to text templates was actually slowing them down, so only do it for markup templates.
| author | cmlenz |
|---|---|
| date | Wed, 05 Sep 2007 13:06:59 +0000 |
| parents | 3d2909fe1dda |
| children | 54964f7d2253 |
| 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 |
|
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
325 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
|
326 |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
327 .. code-block:: genshi |
| 226 | 328 |
| 329 <div> | |
| 330 <py:match path="greeting"> | |
| 331 <span>Hello ${select('@name')}</span> | |
| 332 </py:match> | |
| 333 <greeting name="Dude" /> | |
| 334 </div> | |
| 335 | |
| 602 | 336 When used this way, the ``py:match`` directive can also be annotated with a |
| 337 couple of optimization hints. For example, the following informs the matching | |
| 338 engine that the match should only be applied once: | |
| 339 | |
| 340 .. code-block:: genshi | |
| 341 | |
| 342 <py:match path="body" once="true"> | |
| 343 <body py:attrs="select('@*')"> | |
| 344 <div id="header">...</div> | |
| 345 ${select("*|text()")} | |
| 346 <div id="footer">...</div> | |
| 347 </body> | |
| 348 </py:match> | |
| 349 | |
| 350 The following optimization hints are recognized: | |
| 351 | |
| 352 +---------------+-----------+-----------------------------------------------+ | |
| 353 | Attribute | Default | Description | | |
| 354 +===============+===========+===============================================+ | |
| 355 | ``once`` | ``false`` | Whether the engine should stop looking for | | |
| 356 | | | more matching elements after the first match. | | |
| 357 | | | Use this on match templates that match | | |
| 358 | | | elements that can only occur once in the | | |
| 359 | | | stream, such as the ``<head>`` or ``<body>`` | | |
| 360 | | | elements in an HTML template, or elements | | |
| 361 | | | with a specific ID. | | |
| 362 +---------------+-----------+-----------------------------------------------+ | |
| 363 | ``recursive`` | ``true`` | Whether the match template should be applied | | |
| 364 | | | to its own output. Note that ``once`` implies | | |
| 365 | | | non-recursive behavior, so this attribute | | |
| 366 | | | only needs to be set for match templates that | | |
| 367 | | | don't also have ``once`` set. | | |
| 368 +---------------+-----------+-----------------------------------------------+ | |
| 369 | |
| 370 .. note:: The ``py:match`` optimization hints were added in the 0.5 release. In | |
| 371 earlier versions, the attributes have no effect. | |
| 372 | |
| 226 | 373 |
| 235 | 374 Variable Binding |
| 237 | 375 ================ |
| 226 | 376 |
| 377 .. _`with`: | |
| 378 | |
| 379 ``py:with`` | |
| 237 | 380 ----------- |
| 226 | 381 |
| 382 The ``py:with`` directive lets you assign expressions to variables, which can | |
| 383 be used to make expressions inside the directive less verbose and more | |
| 384 efficient. For example, if you need use the expression ``author.posts`` more | |
| 385 than once, and that actually results in a database query, assigning the results | |
| 386 to a variable using this directive would probably help. | |
| 387 | |
|
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
388 For example: |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
389 |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
390 .. code-block:: genshi |
| 226 | 391 |
| 392 <div> | |
| 393 <span py:with="y=7; z=x+10">$x $y $z</span> | |
| 394 </div> | |
| 395 | |
|
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
396 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
|
397 |
|
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
|
398 .. code-block:: xml |
| 226 | 399 |
| 400 <div> | |
| 401 <span>42 7 52</span> | |
| 402 </div> | |
| 403 | |
|
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
404 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
|
405 |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
406 .. code-block:: genshi |
| 226 | 407 |
| 408 <div> | |
| 409 <py:with vars="y=7; z=x+10">$x $y $z</py:with> | |
| 410 </div> | |
| 411 | |
| 412 Note that if a variable of the same name already existed outside of the scope | |
| 413 of the ``py:with`` directive, it will **not** be overwritten. Instead, it | |
| 414 will have the same value it had prior to the ``py:with`` assignment. | |
| 230 | 415 Effectively, this means that variables are immutable in Genshi. |
| 226 | 416 |
| 417 | |
| 235 | 418 Structure Manipulation |
| 237 | 419 ====================== |
| 235 | 420 |
| 421 .. _`py:attrs`: | |
| 422 | |
| 423 ``py:attrs`` | |
| 237 | 424 ------------ |
| 235 | 425 |
|
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
426 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
|
427 |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
428 .. code-block:: genshi |
| 235 | 429 |
| 430 <ul> | |
| 431 <li py:attrs="foo">Bar</li> | |
| 432 </ul> | |
| 433 | |
| 434 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
|
435 produce: |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
436 |
|
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
|
437 .. code-block:: xml |
| 235 | 438 |
| 439 <ul> | |
| 440 <li class="collapse">Bar</li> | |
| 441 </ul> | |
| 442 | |
| 443 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
|
444 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
|
445 |
|
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
|
446 .. code-block:: xml |
| 235 | 447 |
| 448 <ul> | |
| 449 <li>Bar</li> | |
| 450 </ul> | |
| 451 | |
| 452 This directive can only be used as an attribute. | |
| 453 | |
| 454 | |
| 455 .. _`py:content`: | |
| 456 | |
| 457 ``py:content`` | |
| 237 | 458 -------------- |
| 235 | 459 |
| 460 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
|
461 expression: |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
462 |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
463 .. code-block:: genshi |
| 235 | 464 |
| 465 <ul> | |
| 466 <li py:content="bar">Hello</li> | |
| 467 </ul> | |
| 468 | |
|
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
469 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
|
470 |
|
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
|
471 .. code-block:: xml |
| 235 | 472 |
| 473 <ul> | |
| 474 <li>Bye</li> | |
| 475 </ul> | |
| 476 | |
| 477 This directive can only be used as an attribute. | |
| 478 | |
| 479 | |
| 480 .. _`py:replace`: | |
| 481 | |
| 482 ``py:replace`` | |
| 237 | 483 -------------- |
| 235 | 484 |
| 485 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
|
486 expression: |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
487 |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
488 .. code-block:: genshi |
| 235 | 489 |
| 490 <div> | |
| 491 <span py:replace="bar">Hello</span> | |
| 492 </div> | |
| 493 | |
|
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
494 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
|
495 |
|
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
|
496 .. code-block:: xml |
| 235 | 497 |
| 498 <div> | |
| 499 Bye | |
| 500 </div> | |
| 501 | |
| 502 This directive can only be used as an attribute. | |
| 503 | |
| 504 | |
| 505 .. _`py:strip`: | |
| 506 | |
| 507 ``py:strip`` | |
| 237 | 508 ------------ |
| 235 | 509 |
| 510 This directive conditionally strips the top-level element from the output. When | |
| 511 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
|
512 stripped from the output: |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
513 |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
514 .. code-block:: genshi |
| 235 | 515 |
| 516 <div> | |
| 517 <div py:strip="True"><b>foo</b></div> | |
| 518 </div> | |
| 519 | |
|
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
520 This would be rendered as: |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
521 |
|
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
|
522 .. code-block:: xml |
| 235 | 523 |
| 524 <div> | |
| 525 <b>foo</b> | |
| 526 </div> | |
| 527 | |
| 528 As a shorthand, if the value of the ``py:strip`` attribute is empty, that has | |
| 529 the same effect as using a truth value (i.e. the element is stripped). | |
| 530 | |
| 531 | |
| 226 | 532 .. _order: |
| 533 | |
| 534 Processing Order | |
| 535 ================ | |
| 536 | |
| 537 It is possible to attach multiple directives to a single element, although not | |
| 538 all combinations make sense. When multiple directives are encountered, they are | |
| 539 processed in the following order: | |
| 540 | |
| 541 #. `py:def`_ | |
| 542 #. `py:match`_ | |
| 543 #. `py:when`_ | |
| 544 #. `py:otherwise`_ | |
| 545 #. `py:for`_ | |
| 546 #. `py:if`_ | |
| 547 #. `py:choose`_ | |
| 548 #. `py:with`_ | |
| 549 #. `py:replace`_ | |
| 550 #. `py:content`_ | |
| 551 #. `py:attrs`_ | |
| 552 #. `py:strip`_ | |
| 553 | |
| 554 | |
| 555 .. _includes: | |
| 556 | |
| 557 -------- | |
| 558 Includes | |
| 559 -------- | |
| 560 | |
| 561 To reuse common snippets of template code, you can include other files using | |
| 562 XInclude_. | |
| 563 | |
| 564 .. _xinclude: http://www.w3.org/TR/xinclude/ | |
| 565 | |
| 566 For this, you need to declare the XInclude namespace (commonly bound to the | |
| 567 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
|
568 file to be pulled in: |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
569 |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
570 .. code-block:: genshi |
| 226 | 571 |
| 572 <html xmlns="http://www.w3.org/1999/xhtml" | |
| 230 | 573 xmlns:py="http://genshi.edgewall.org/" |
| 226 | 574 xmlns:xi="http://www.w3.org/2001/XInclude"> |
| 575 <xi:include href="base.html" /> | |
| 576 ... | |
| 577 </html> | |
| 578 | |
| 579 Include paths are relative to the filename of the template currently being | |
| 580 processed. So if the example above was in the file "``myapp/index.html``" | |
| 581 (relative to the template search path), the XInclude processor would look for | |
| 582 the included file at "``myapp/base.html``". You can also use Unix-style | |
| 583 relative paths, for example "``../base.html``" to look in the parent directory. | |
| 584 | |
| 585 Any content included this way is inserted into the generated output instead of | |
| 586 the ``<xi:include>`` element. The included template sees the same context data. | |
| 587 `Match templates`_ and `macros`_ in the included template are also available to | |
| 588 the including template after the point it was included. | |
| 589 | |
| 590 By default, an error will be raised if an included file is not found. If that's | |
| 591 not what you want, you can specify fallback content that should be used if the | |
| 592 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
|
593 write: |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
594 |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
595 .. code-block:: genshi |
| 226 | 596 |
| 597 <xi:include href="base.html"><xi:fallback /></xi:include> | |
| 598 | |
| 273 | 599 See the `XInclude specification`_ for more about fallback content. Note though |
| 600 that Genshi currently only supports a small subset of XInclude. | |
| 601 | |
| 602 .. _`xinclude specification`: http://www.w3.org/TR/xinclude/ | |
| 226 | 603 |
|
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
|
604 |
|
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
|
605 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
|
606 ================ |
|
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
|
607 |
| 230 | 608 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
|
609 attribute accepts expressions, and directives_ can be used on the |
| 226 | 610 ``<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
|
611 things like conditional includes: |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
612 |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
613 .. code-block:: genshi |
| 226 | 614 |
| 615 <xi:include href="${name}.html" py:if="not in_popup" | |
| 616 py:for="name in ('foo', 'bar', 'baz')" /> | |
| 617 | |
| 618 | |
|
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
|
619 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
|
620 ======================== |
|
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
|
621 |
|
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
|
622 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
|
623 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
|
624 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
|
625 |
|
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
|
626 .. 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
|
627 |
|
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 <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
|
629 |
|
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 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
|
631 `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
|
632 |
|
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
|
633 .. _`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
|
634 |
|
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
|
635 |
| 226 | 636 .. _comments: |
| 637 | |
| 638 -------- | |
| 639 Comments | |
| 640 -------- | |
| 641 | |
|
510
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
642 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
|
643 |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
644 .. code-block:: genshi |
| 226 | 645 |
| 646 <!-- this is a comment --> | |
| 647 | |
| 648 However, such comments get passed through the processing pipeline and are by | |
| 649 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
|
650 text with an exclamation mark: |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
651 |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
652 .. code-block:: genshi |
| 226 | 653 |
| 654 <!-- !this is a comment too, but one that will be stripped from the output --> | |
| 655 | |
| 656 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
|
657 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
|
658 |
|
1bdccd3bda00
Use syntax highlighting on all the other doc pages, too.
cmlenz
parents:
451
diff
changeset
|
659 .. code-block:: genshi |
| 226 | 660 |
| 661 <!--! this is a comment too, but one that will be stripped from the output --> |