Mercurial > genshi > mirror
comparison doc/xml-templates.txt @ 226:4d8a9e03b23d trunk
Add reStructuredText documentation files.
author | cmlenz |
---|---|
date | Fri, 08 Sep 2006 08:44:31 +0000 |
parents | |
children | 84168828b074 |
comparison
equal
deleted
inserted
replaced
225:16d7b5db7ef4 | 226:4d8a9e03b23d |
---|---|
1 .. -*- mode: rst; encoding: utf-8 -*- | |
2 | |
3 ============================ | |
4 Markup XML Template Language | |
5 ============================ | |
6 | |
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 --> |