Mercurial > genshi > mirror

comparison doc/xml-templates.txt @ 241:4d81439bc097 trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* 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 670f543fd8c2
children fa07ab5a7e53
comparison
equal deleted inserted replaced
240:37039af315da 241:4d81439bc097
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
Copyright (C) 2012-2017 Edgewall Software