Mercurial > genshi > mirror

annotate doc/xml-templates.txt @ 242:71062601458a trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Implement comments and directive escaping for text templates.
author cmlenz
date Wed, 13 Sep 2006 16:44:12 +0000
parents 4d81439bc097
children fa07ab5a7e53
rev   line source
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
2
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
3 ============================
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
4 Genshi XML Template Language
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
5 ============================
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
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
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
10
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
11 .. _kid: http://kid-templating.org/
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
12 .. _python: http://www.python.org/
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
13 .. _xslt: http://www.w3.org/TR/xslt
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
14 .. _tal: http://www.zope.org/Wikis/DevSite/Projects/ZPT/TAL
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
15 .. _php: http://www.php.net/
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
16
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
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
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
20 attributes identified by a separate namespace) that affect how the template is
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
21 rendered, and template expressions_ that are dynamically substituted by
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
22 variable data.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
23
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
24
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
25 .. contents:: Contents
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
26 :depth: 3
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
27 .. sectnum::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
28
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
29 ----------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
30 Python API
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
31 ----------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
32
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
33 The Python code required for templating with Genshi is generally based on the
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
34 following pattern:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
35
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
36 * Attain a ``MarkupTemplate`` object from a string or file object containing
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
37 the template XML source. This can either be done directly, or through a
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
38 ``TemplateLoader`` instance.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
39 * Call the ``generate()`` method of the template, passing any data that should
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
40 be made available to the template as keyword arguments.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
41 * Serialize the resulting stream using its ``render()`` method.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
42
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
43 For example::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
44
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
45 from genshi.template import MarkupTemplate
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
46
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
47 tmpl = MarkupTemplate('<h1>$title</h1>')
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
48 stream = tmpl.generate(title='Hello, world!')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
49 print stream.render('xhtml')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
50
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
51 That code would produce the following output::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
52
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
53 <h1>Hello, world!</h1>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
54
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
55 However, if you want includes_ to work, you should attain the template instance
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
56 through a ``TemplateLoader``, and load the template from a file::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
57
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
58 from genshi.template import TemplateLoader
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
59
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
60 loader = TemplateLoader([templates_dir])
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
61 tmpl = loader.load('test.html')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
62 stream = tmpl.generate(title='Hello, world!')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
63 print stream.render('xhtml')
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
64
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
65
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
66 .. _`expressions`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
67
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
68 --------------------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
69 Template Expressions
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
70 --------------------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
71
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
72 Python_ expressions can be used in text and attribute values. An expression is
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
73 substituted with the result of its evaluation against the template data.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
74 Expressions need to prefixed with a dollar sign (``$``) and usually enclosed in
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
75 curly braces (``{…}``).
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
76
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
77 If the expression starts with a letter and contains only letters and digits,
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
78 the curly braces may be omitted. In all other cases, the braces are required so
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
79 that the template processors knows where the expression ends::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
80
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
81 >>> from genshi.template import MarkupTemplate
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
82 >>> tmpl = MarkupTemplate('<em>${items[0].capitalize()} item</em>')
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
83 >>> print tmpl.generate(items=['first', 'second'])
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
84 <em>First item</em>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
85
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
86 Expressions support the full power of Python. In addition, it is possible to
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
87 access items in a dictionary using “dotted notation” (i.e. as if they were
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
88 attributes), and vice-versa (i.e. access attributes as if they were items in a
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
89 dictionary)::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
90
241
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
91 >>> from genshi.template import MarkupTemplate
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
92 >>> tmpl = MarkupTemplate('<em>${dict.foo}</em>')
4d81439bc097 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
93 >>> print tmpl.generate(dict={'foo': 'bar'})
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
94 <em>bar</em>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
95
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
96
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
97 .. _`directives`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
98
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
99 -------------------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
100 Template Directives
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
101 -------------------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
102
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
103 Directives are elements and/or attributes in the template that are identified
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
104 by the namespace ``http://genshi.edgewall.org/``. They can affect how the
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
105 template is rendered in a number of ways: Genshi provides directives for
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
106 conditionals and looping, among others.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
107
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
108 To use directives in a template, the namespace should be declared, which is
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
109 usually done on the root element::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
110
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
111 <html xmlns="http://www.w3.org/1999/xhtml"
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
112 xmlns:py="http://genshi.edgewall.org/"
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
113 lang="en">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
114 ...
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
115 </html>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
116
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
117 In this example, the default namespace is set to the XHTML namespace, and the
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
118 namespace for Genshi directives is bound to the prefix “py”.
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
119
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
120 All directives can be applied as attributes, and some can also be used as
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
121 elements. The ``if`` directives for conditionals, for example, can be used in
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
122 both ways::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
123
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
124 <html xmlns="http://www.w3.org/1999/xhtml"
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
125 xmlns:py="http://genshi.edgewall.org/"
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
126 lang="en">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
127 ...
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
128 <div py:if="foo">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
129 <p>Bar</p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
130 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
131 ...
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
132 </html>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
133
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
134 This is basically equivalent to the following::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
135
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
136 <html xmlns="http://www.w3.org/1999/xhtml"
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
137 xmlns:py="http://genshi.edgewall.org/"
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
138 lang="en">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
139 ...
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
140 <py:if test="foo">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
141 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
142 <p>Bar</p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
143 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
144 </py:if>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
145 ...
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
146 </html>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
147
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
148 The rationale behind the second form is that directives do not always map
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
149 naturally to elements in the template. In such cases, the ``py:strip``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
150 directive can be used to strip off the unwanted element, or the directive can
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
151 simply be used as an element.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
152
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
153
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
154 Conditional Sections
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
155 ====================
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
156
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
157 .. _`py:if`:
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
158
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
159 ``py:if``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
160 ---------
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
161
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
162 The element is only rendered if the expression evaluates to a truth value::
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
163
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
164 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
165 <b py:if="foo">${bar}</b>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
166 </div>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
167
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
168 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
169 would produce::
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
170
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
171 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
172 <b>Hello</b>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
173 </div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
174
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
175 This directive can also be used as an element::
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
176
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
177 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
178 <py:if test="foo">
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
179 <b>${bar}</b>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
180 </py:if>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
181 </div>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
182
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
183 .. _`py:choose`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
184 .. _`py:when`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
185 .. _`py:otherwise`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
186
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
187 ``py:choose``
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
188 -------------
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
189
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
190 The ``py:choose`` directive, in combination with the directives ``py:when``
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
191 and ``py:otherwise`` provides advanced contional processing for rendering one
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
192 of several alternatives. The first matching ``py:when`` branch is rendered, or,
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
193 if no ``py:when`` branch matches, the ``py:otherwise`` branch is be rendered.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
194
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
195 If the ``py:choose`` directive is empty the nested ``py:when`` directives will
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
196 be tested for truth::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
197
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
198 <div py:choose="">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
199 <span py:when="0 == 1">0</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
200 <span py:when="1 == 1">1</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
201 <span py:otherwise="">2</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
202 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
203
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
204 This would produce the following output::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
205
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
206 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
207 <span>1</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
208 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
209
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
210 If the ``py:choose`` directive contains an expression the nested ``py:when``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
211 directives will be tested for equality to the parent ``py:choose`` value::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
212
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
213 <div py:choose="1">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
214 <span py:when="0">0</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
215 <span py:when="1">1</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
216 <span py:otherwise="">2</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
217 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
218
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
219 This would produce the following output::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
220
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
221 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
222 <span>1</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
223 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
224
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
225
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
226 Looping
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
227 =======
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
228
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
229 .. _`py:for`:
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
230
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
231 ``py:for``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
232 ----------
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
233
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
234 The element is repeated for every item in an iterable::
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
235
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
236 <ul>
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
237 <li py:for="item in items">${item}</li>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
238 </ul>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
239
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
240 Given ``items=[1, 2, 3]`` in the context data, this would produce::
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
241
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
242 <ul>
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
243 <li>1</li><li>2</li><li>3</li>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
244 </ul>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
245
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
246 This directive can also be used as an element::
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
247
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
248 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
249 <py:for each="item in items">
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
250 <li>${item}</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
251 </py:for>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
252 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
253
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
254
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
255 Snippet Reuse
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
256 =============
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
257
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
258 .. _`py:def`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
259 .. _`macros`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
260
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
261 ``py:def``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
262 ----------
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
263
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
264 The ``py:def`` directive can be used to create macros, i.e. snippets of
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
265 template code that have a name and optionally some parameters, and that can be
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
266 inserted in other places::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
267
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
268 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
269 <p py:def="greeting(name)" class="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
270 Hello, ${name}!
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
271 </p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
272 ${greeting('world')}
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
273 ${greeting('everyone else')}
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
274 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
275
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
276 The above would be rendered to::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
277
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
278 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
279 <p class="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
280 Hello, world!
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
281 </p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
282 <p class="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
283 Hello, everyone else!
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
284 </p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
285 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
286
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
287 If a macro doesn't require parameters, it can be defined as well as called
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
288 without the parenthesis. For example::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
289
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
290 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
291 <p py:def="greeting" class="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
292 Hello, world!
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
293 </p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
294 ${greeting}
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
295 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
296
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
297 The above would be rendered to::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
298
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
299 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
300 <p class="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
301 Hello, world!
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
302 </p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
303 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
304
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
305 This directive can also be used as an element::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
306
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
307 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
308 <py:def function="greeting(name)">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
309 <p class="greeting">Hello, ${name}!</p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
310 </py:def>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
311 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
312
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
313
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
314 .. _Match Templates:
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
315 .. _`py:match`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
316
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
317 ``py:match``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
318 ------------
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
319
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
320 This directive defines a *match template*: given an XPath expression, it
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
321 replaces any element in the template that matches the expression with its own
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
322 content.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
323
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
324 For example, the match template defined in the following template matches any
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
325 element with the tag name “greeting”::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
326
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
327 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
328 <span py:match="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
329 Hello ${select('@name')}
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
330 </span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
331 <greeting name="Dude" />
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
332 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
333
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
334 This would result in the following output::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
335
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
336 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
337 <span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
338 Hello Dude
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
339 </span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
340 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
341
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
342 Inside the body of a ``py:match`` directive, the ``select(path)`` function is
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
343 made available so that parts or all of the original element can be incorporated
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
344 in the output of the match template. See [wiki:GenshiStream#UsingXPath] for
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
345 more information about this function.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
346
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
347 This directive can also be used as an element::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
348
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
349 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
350 <py:match path="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
351 <span>Hello ${select('@name')}</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
352 </py:match>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
353 <greeting name="Dude" />
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
354 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
355
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
356
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
357 Variable Binding
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
358 ================
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
359
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
360 .. _`with`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
361
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
362 ``py:with``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
363 -----------
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
364
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
365 The ``py:with`` directive lets you assign expressions to variables, which can
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
366 be used to make expressions inside the directive less verbose and more
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
367 efficient. For example, if you need use the expression ``author.posts`` more
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
368 than once, and that actually results in a database query, assigning the results
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
369 to a variable using this directive would probably help.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
370
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
371 For example::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
372
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
373 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
374 <span py:with="y=7; z=x+10">$x $y $z</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
375 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
376
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
377 Given ``x=42`` in the context data, this would produce::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
378
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
379 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
380 <span>42 7 52</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
381 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
382
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
383 This directive can also be used as an element::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
384
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
385 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
386 <py:with vars="y=7; z=x+10">$x $y $z</py:with>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
387 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
388
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
389 Note that if a variable of the same name already existed outside of the scope
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
390 of the ``py:with`` directive, it will **not** be overwritten. Instead, it
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
391 will have the same value it had prior to the ``py:with`` assignment.
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
392 Effectively, this means that variables are immutable in Genshi.
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
393
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
394
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
395 Structure Manipulation
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
396 ======================
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
397
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
398 .. _`py:attrs`:
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
399
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
400 ``py:attrs``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
401 ------------
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
402
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
403 This directive adds, modifies or removes attributes from the element::
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
404
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
405 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
406 <li py:attrs="foo">Bar</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
407 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
408
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
409 Given ``foo={'class': 'collapse'}`` in the template context, this would
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
410 produce::
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
411
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
412 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
413 <li class="collapse">Bar</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
414 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
415
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
416 Attributes with the value ``None`` are omitted, so given ``foo={'class': None}``
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
417 in the context for the same template this would produce::
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
418
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
419 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
420 <li>Bar</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
421 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
422
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
423 This directive can only be used as an attribute.
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
424
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
425
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
426 .. _`py:content`:
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
427
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
428 ``py:content``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
429 --------------
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
430
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
431 This directive replaces any nested content with the result of evaluating the
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
432 expression::
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
433
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
434 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
435 <li py:content="bar">Hello</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
436 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
437
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
438 Given ``bar='Bye'`` in the context data, this would produce::
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
439
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
440 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
441 <li>Bye</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
442 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
443
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
444 This directive can only be used as an attribute.
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
445
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
446
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
447 .. _`py:replace`:
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
448
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
449 ``py:replace``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
450 --------------
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
451
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
452 This directive replaces the element itself with the result of evaluating the
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
453 expression::
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
454
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
455 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
456 <span py:replace="bar">Hello</span>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
457 </div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
458
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
459 Given ``bar='Bye'`` in the context data, this would produce::
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
460
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
461 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
462 Bye
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
463 </div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
464
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
465 This directive can only be used as an attribute.
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
466
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
467
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
468 .. _`py:strip`:
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
469
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
470 ``py:strip``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
471 ------------
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
472
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
473 This directive conditionally strips the top-level element from the output. When
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
474 the value of the ``py:strip`` attribute evaluates to ``True``, the element is
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
475 stripped from the output::
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
476
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
477 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
478 <div py:strip="True"><b>foo</b></div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
479 </div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
480
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
481 This would be rendered as::
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
482
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
483 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
484 <b>foo</b>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
485 </div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
486
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
487 As a shorthand, if the value of the ``py:strip`` attribute is empty, that has
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
488 the same effect as using a truth value (i.e. the element is stripped).
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
489
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
490
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
491 .. _order:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
492
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
493 Processing Order
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
494 ================
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
495
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
496 It is possible to attach multiple directives to a single element, although not
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
497 all combinations make sense. When multiple directives are encountered, they are
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
498 processed in the following order:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
499
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
500 #. `py:def`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
501 #. `py:match`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
502 #. `py:when`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
503 #. `py:otherwise`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
504 #. `py:for`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
505 #. `py:if`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
506 #. `py:choose`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
507 #. `py:with`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
508 #. `py:replace`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
509 #. `py:content`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
510 #. `py:attrs`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
511 #. `py:strip`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
512
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
513
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
514 .. _includes:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
515
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
516 --------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
517 Includes
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
518 --------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
519
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
520 To reuse common snippets of template code, you can include other files using
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
521 XInclude_.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
522
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
523 .. _xinclude: http://www.w3.org/TR/xinclude/
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
524
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
525 For this, you need to declare the XInclude namespace (commonly bound to the
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
526 prefix “xi”) and use the ``<xi:include>`` element where you want the external
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
527 file to be pulled in::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
528
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
529 <html xmlns="http://www.w3.org/1999/xhtml"
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
530 xmlns:py="http://genshi.edgewall.org/"
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
531 xmlns:xi="http://www.w3.org/2001/XInclude">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
532 <xi:include href="base.html" />
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
533 ...
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
534 </html>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
535
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
536 Include paths are relative to the filename of the template currently being
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
537 processed. So if the example above was in the file "``myapp/index.html``"
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
538 (relative to the template search path), the XInclude processor would look for
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
539 the included file at "``myapp/base.html``". You can also use Unix-style
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
540 relative paths, for example "``../base.html``" to look in the parent directory.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
541
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
542 Any content included this way is inserted into the generated output instead of
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
543 the ``<xi:include>`` element. The included template sees the same context data.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
544 `Match templates`_ and `macros`_ in the included template are also available to
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
545 the including template after the point it was included.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
546
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
547 By default, an error will be raised if an included file is not found. If that's
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
548 not what you want, you can specify fallback content that should be used if the
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
549 include fails. For example, to to make the include above fail silently, you'd
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
550 write:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
551
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
552 <xi:include href="base.html"><xi:fallback /></xi:include>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
553
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
554 See the XInclude_ for more about fallback content. Note though that Genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
555 currently only supports a small subset of XInclude.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
556
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
557 Incudes in Genshi are fully dynamic: Just like normal attributes, the `href`
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
558 attribute accepts expressions_, and directives_ can be used on the
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
559 ``<xi:include />`` element just as on any other element, meaning you can do
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
560 things like conditional includes::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
561
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
562 <xi:include href="${name}.html" py:if="not in_popup"
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
563 py:for="name in ('foo', 'bar', 'baz')" />
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
564
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
565
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
566 .. _comments:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
567
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
568 --------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
569 Comments
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
570 --------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
571
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
572 Normal XML/HTML comment syntax can be used in templates::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
573
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
574 <!-- this is a comment -->
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
575
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
576 However, such comments get passed through the processing pipeline and are by
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
577 default included in the final output. If that's not desired, prefix the comment
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
578 text with an exclamation mark::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
579
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
580 <!-- !this is a comment too, but one that will be stripped from the output -->
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
581
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
582 Note that it does not matter whether there's whitespace before or after the
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
583 exclamation mark, so the above could also be written as follows::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
584
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
585 <!--! this is a comment too, but one that will be stripped from the output -->
Copyright (C) 2012-2017 Edgewall Software