Mercurial > genshi > genshi-test
comparison doc/xml-templates.txt @ 241:bbed6d426678
* Added basic documentation for the text-based template language.
* Directives in text templates are now closed with a simple `#end` line instead of the longer `#end<name>`.
author | cmlenz |
---|---|
date | Wed, 13 Sep 2006 14:52:58 +0000 |
parents | ad52b350e132 |
children | 78ae64ef822e |
comparison
equal
deleted
inserted
replaced
240:682471a23f5b | 241:bbed6d426678 |
---|---|
2 | 2 |
3 ============================ | 3 ============================ |
4 Genshi XML Template Language | 4 Genshi XML Template Language |
5 ============================ | 5 ============================ |
6 | 6 |
7 Genshi provides a simple XML-based template language that is heavily inspired | 7 Genshi provides a XML-based template language that is heavily inspired by Kid_, |
8 by Kid_, which in turn was inspired by a number of existing template languages, | 8 which in turn was inspired by a number of existing template languages, namely |
9 namely XSLT_, TAL_, and PHP_. | 9 XSLT_, TAL_, and PHP_. |
10 | 10 |
11 .. _kid: http://kid-templating.org/ | 11 .. _kid: http://kid-templating.org/ |
12 .. _python: http://www.python.org/ | 12 .. _python: http://www.python.org/ |
13 .. _xslt: http://www.w3.org/TR/xslt | 13 .. _xslt: http://www.w3.org/TR/xslt |
14 .. _tal: http://www.zope.org/Wikis/DevSite/Projects/ZPT/TAL | 14 .. _tal: http://www.zope.org/Wikis/DevSite/Projects/ZPT/TAL |
15 .. _php: http://www.php.net/ | 15 .. _php: http://www.php.net/ |
16 | 16 |
17 This document describes the template language and will be most useful as | 17 This document describes the template language and will be most useful as |
18 reference to those developing Genshi templates. Templates are XML files of some | 18 reference to those developing Genshi XML templates. Templates are XML files of |
19 kind (such as XHTML) that include processing directives_ (elements or | 19 some kind (such as XHTML) that include processing directives_ (elements or |
20 attributes identified by a separate namespace) that affect how the template is | 20 attributes identified by a separate namespace) that affect how the template is |
21 rendered, and template expressions_ that are dynamically substituted by | 21 rendered, and template expressions_ that are dynamically substituted by |
22 variable data. | 22 variable data. |
23 | 23 |
24 | 24 |
31 ---------- | 31 ---------- |
32 | 32 |
33 The Python code required for templating with Genshi is generally based on the | 33 The Python code required for templating with Genshi is generally based on the |
34 following pattern: | 34 following pattern: |
35 | 35 |
36 * Attain a ``Template`` object from a string or file object containing the | 36 * Attain a ``MarkupTemplate`` object from a string or file object containing |
37 template XML source. This can either be done directly, or through a | 37 the template XML source. This can either be done directly, or through a |
38 ``TemplateLoader`` instance. | 38 ``TemplateLoader`` instance. |
39 * Call the ``generate()`` method of the template, passing any data that should | 39 * Call the ``generate()`` method of the template, passing any data that should |
40 be made available to the template as keyword arguments. | 40 be made available to the template as keyword arguments. |
41 * Serialize the resulting stream using its ``render()`` method. | 41 * Serialize the resulting stream using its ``render()`` method. |
42 | 42 |
43 For example:: | 43 For example:: |
44 | 44 |
45 from genshi.template import Template | 45 from genshi.template import MarkupTemplate |
46 | 46 |
47 tmpl = Template('<h1>$title</h1>') | 47 tmpl = MarkupTemplate('<h1>$title</h1>') |
48 stream = tmpl.generate(title='Hello, world!') | 48 stream = tmpl.generate(title='Hello, world!') |
49 print stream.render('xhtml') | 49 print stream.render('xhtml') |
50 | 50 |
51 That code would produce the following output:: | 51 That code would produce the following output:: |
52 | 52 |
76 | 76 |
77 If the expression starts with a letter and contains only letters and digits, | 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 | 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:: | 79 that the template processors knows where the expression ends:: |
80 | 80 |
81 >>> from genshi.template import Context, Template | 81 >>> from genshi.template import MarkupTemplate |
82 >>> tmpl = Template('<em>${items[0].capitalize()} item</em>') | 82 >>> tmpl = MarkupTemplate('<em>${items[0].capitalize()} item</em>') |
83 >>> print tmpl.generate(Context(items=['first', 'second'])) | 83 >>> print tmpl.generate(items=['first', 'second']) |
84 <em>First item</em> | 84 <em>First item</em> |
85 | 85 |
86 Expressions support the full power of Python. In addition, it is possible to | 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 | 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 | 88 attributes), and vice-versa (i.e. access attributes as if they were items in a |
89 dictionary):: | 89 dictionary):: |
90 | 90 |
91 >>> from genshi.template import Context, Template | 91 >>> from genshi.template import MarkupTemplate |
92 >>> tmpl = Template('<em>${dict.foo}</em>') | 92 >>> tmpl = MarkupTemplate('<em>${dict.foo}</em>') |
93 >>> print tmpl.generate(Context(dict={'foo': 'bar'})) | 93 >>> print tmpl.generate(dict={'foo': 'bar'}) |
94 <em>bar</em> | 94 <em>bar</em> |
95 | 95 |
96 | 96 |
97 .. _`directives`: | 97 .. _`directives`: |
98 | 98 |