Mercurial > genshi > mirror
annotate doc/xml-templates.txt @ 450:94601511cd68 trunk
Extend the I18n extraction to also yield function names if applicable.
author | cmlenz |
---|---|
date | Fri, 13 Apr 2007 20:58:48 +0000 |
parents | 97544725bb7f |
children | 4183fd29fa4e |
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 | |
230 | 280 in the output of the match template. See [wiki:GenshiStream#UsingXPath] for |
226 | 281 more information about this function. |
282 | |
283 This directive can also be used as an element:: | |
284 | |
285 <div> | |
286 <py:match path="greeting"> | |
287 <span>Hello ${select('@name')}</span> | |
288 </py:match> | |
289 <greeting name="Dude" /> | |
290 </div> | |
291 | |
292 | |
235 | 293 Variable Binding |
237 | 294 ================ |
226 | 295 |
296 .. _`with`: | |
297 | |
298 ``py:with`` | |
237 | 299 ----------- |
226 | 300 |
301 The ``py:with`` directive lets you assign expressions to variables, which can | |
302 be used to make expressions inside the directive less verbose and more | |
303 efficient. For example, if you need use the expression ``author.posts`` more | |
304 than once, and that actually results in a database query, assigning the results | |
305 to a variable using this directive would probably help. | |
306 | |
307 For example:: | |
308 | |
309 <div> | |
310 <span py:with="y=7; z=x+10">$x $y $z</span> | |
311 </div> | |
312 | |
313 Given ``x=42`` in the context data, this would produce:: | |
314 | |
315 <div> | |
316 <span>42 7 52</span> | |
317 </div> | |
318 | |
319 This directive can also be used as an element:: | |
320 | |
321 <div> | |
322 <py:with vars="y=7; z=x+10">$x $y $z</py:with> | |
323 </div> | |
324 | |
325 Note that if a variable of the same name already existed outside of the scope | |
326 of the ``py:with`` directive, it will **not** be overwritten. Instead, it | |
327 will have the same value it had prior to the ``py:with`` assignment. | |
230 | 328 Effectively, this means that variables are immutable in Genshi. |
226 | 329 |
330 | |
235 | 331 Structure Manipulation |
237 | 332 ====================== |
235 | 333 |
334 .. _`py:attrs`: | |
335 | |
336 ``py:attrs`` | |
237 | 337 ------------ |
235 | 338 |
339 This directive adds, modifies or removes attributes from the element:: | |
340 | |
341 <ul> | |
342 <li py:attrs="foo">Bar</li> | |
343 </ul> | |
344 | |
345 Given ``foo={'class': 'collapse'}`` in the template context, this would | |
346 produce:: | |
347 | |
348 <ul> | |
349 <li class="collapse">Bar</li> | |
350 </ul> | |
351 | |
352 Attributes with the value ``None`` are omitted, so given ``foo={'class': None}`` | |
353 in the context for the same template this would produce:: | |
354 | |
355 <ul> | |
356 <li>Bar</li> | |
357 </ul> | |
358 | |
359 This directive can only be used as an attribute. | |
360 | |
361 | |
362 .. _`py:content`: | |
363 | |
364 ``py:content`` | |
237 | 365 -------------- |
235 | 366 |
367 This directive replaces any nested content with the result of evaluating the | |
368 expression:: | |
369 | |
370 <ul> | |
371 <li py:content="bar">Hello</li> | |
372 </ul> | |
373 | |
374 Given ``bar='Bye'`` in the context data, this would produce:: | |
375 | |
376 <ul> | |
377 <li>Bye</li> | |
378 </ul> | |
379 | |
380 This directive can only be used as an attribute. | |
381 | |
382 | |
383 .. _`py:replace`: | |
384 | |
385 ``py:replace`` | |
237 | 386 -------------- |
235 | 387 |
388 This directive replaces the element itself with the result of evaluating the | |
389 expression:: | |
390 | |
391 <div> | |
392 <span py:replace="bar">Hello</span> | |
393 </div> | |
394 | |
395 Given ``bar='Bye'`` in the context data, this would produce:: | |
396 | |
397 <div> | |
398 Bye | |
399 </div> | |
400 | |
401 This directive can only be used as an attribute. | |
402 | |
403 | |
404 .. _`py:strip`: | |
405 | |
406 ``py:strip`` | |
237 | 407 ------------ |
235 | 408 |
409 This directive conditionally strips the top-level element from the output. When | |
410 the value of the ``py:strip`` attribute evaluates to ``True``, the element is | |
411 stripped from the output:: | |
412 | |
413 <div> | |
414 <div py:strip="True"><b>foo</b></div> | |
415 </div> | |
416 | |
417 This would be rendered as:: | |
418 | |
419 <div> | |
420 <b>foo</b> | |
421 </div> | |
422 | |
423 As a shorthand, if the value of the ``py:strip`` attribute is empty, that has | |
424 the same effect as using a truth value (i.e. the element is stripped). | |
425 | |
426 | |
226 | 427 .. _order: |
428 | |
429 Processing Order | |
430 ================ | |
431 | |
432 It is possible to attach multiple directives to a single element, although not | |
433 all combinations make sense. When multiple directives are encountered, they are | |
434 processed in the following order: | |
435 | |
436 #. `py:def`_ | |
437 #. `py:match`_ | |
438 #. `py:when`_ | |
439 #. `py:otherwise`_ | |
440 #. `py:for`_ | |
441 #. `py:if`_ | |
442 #. `py:choose`_ | |
443 #. `py:with`_ | |
444 #. `py:replace`_ | |
445 #. `py:content`_ | |
446 #. `py:attrs`_ | |
447 #. `py:strip`_ | |
448 | |
449 | |
450 .. _includes: | |
451 | |
452 -------- | |
453 Includes | |
454 -------- | |
455 | |
456 To reuse common snippets of template code, you can include other files using | |
457 XInclude_. | |
458 | |
459 .. _xinclude: http://www.w3.org/TR/xinclude/ | |
460 | |
461 For this, you need to declare the XInclude namespace (commonly bound to the | |
462 prefix “xi”) and use the ``<xi:include>`` element where you want the external | |
463 file to be pulled in:: | |
464 | |
465 <html xmlns="http://www.w3.org/1999/xhtml" | |
230 | 466 xmlns:py="http://genshi.edgewall.org/" |
226 | 467 xmlns:xi="http://www.w3.org/2001/XInclude"> |
468 <xi:include href="base.html" /> | |
469 ... | |
470 </html> | |
471 | |
472 Include paths are relative to the filename of the template currently being | |
473 processed. So if the example above was in the file "``myapp/index.html``" | |
474 (relative to the template search path), the XInclude processor would look for | |
475 the included file at "``myapp/base.html``". You can also use Unix-style | |
476 relative paths, for example "``../base.html``" to look in the parent directory. | |
477 | |
478 Any content included this way is inserted into the generated output instead of | |
479 the ``<xi:include>`` element. The included template sees the same context data. | |
480 `Match templates`_ and `macros`_ in the included template are also available to | |
481 the including template after the point it was included. | |
482 | |
483 By default, an error will be raised if an included file is not found. If that's | |
484 not what you want, you can specify fallback content that should be used if the | |
485 include fails. For example, to to make the include above fail silently, you'd | |
273 | 486 write:: |
226 | 487 |
488 <xi:include href="base.html"><xi:fallback /></xi:include> | |
489 | |
273 | 490 See the `XInclude specification`_ for more about fallback content. Note though |
491 that Genshi currently only supports a small subset of XInclude. | |
492 | |
493 .. _`xinclude specification`: http://www.w3.org/TR/xinclude/ | |
226 | 494 |
230 | 495 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
|
496 attribute accepts expressions, and directives_ can be used on the |
226 | 497 ``<xi:include />`` element just as on any other element, meaning you can do |
498 things like conditional includes:: | |
499 | |
500 <xi:include href="${name}.html" py:if="not in_popup" | |
501 py:for="name in ('foo', 'bar', 'baz')" /> | |
502 | |
503 | |
504 .. _comments: | |
505 | |
506 -------- | |
507 Comments | |
508 -------- | |
509 | |
510 Normal XML/HTML comment syntax can be used in templates:: | |
511 | |
512 <!-- this is a comment --> | |
513 | |
514 However, such comments get passed through the processing pipeline and are by | |
515 default included in the final output. If that's not desired, prefix the comment | |
516 text with an exclamation mark:: | |
517 | |
518 <!-- !this is a comment too, but one that will be stripped from the output --> | |
519 | |
520 Note that it does not matter whether there's whitespace before or after the | |
521 exclamation mark, so the above could also be written as follows:: | |
522 | |
523 <!--! this is a comment too, but one that will be stripped from the output --> |