Mercurial > genshi > mirror

annotate doc/xml-templates.txt @ 737:ca72e3dc443d trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Implement the `__html__` protocol as suggested in #202. This would allow Genshi to be used in combination with other markup generating tools, as long as they support the same protocol.
author cmlenz
date Thu, 05 Jun 2008 17:00:15 +0000
parents 85ff66a8f453
children 25d6cd05746c
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
442
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
21 rendered, and template expressions that are dynamically substituted by
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
22 variable data.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
23
442
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
24 See `Genshi Templating Basics <templates.html>`_ for general information on
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
25 embedding Python code in templates.
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
26
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
27
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
28 .. contents:: Contents
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
29 :depth: 3
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
30 .. sectnum::
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
31
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
32
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
33 .. _`directives`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
34
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
35 -------------------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
36 Template Directives
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
37 -------------------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
38
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
39 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
40 by the namespace ``http://genshi.edgewall.org/``. They can affect how the
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
41 template is rendered in a number of ways: Genshi provides directives for
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
42 conditionals and looping, among others.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
43
394
cab6b0256019 Minor doc fixes.
cmlenz
parents: 354
diff changeset
44 To use directives in a template, the namespace must be declared, which is
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
45 usually done on the root element:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
46
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
47 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
48
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
49 <html xmlns="http://www.w3.org/1999/xhtml"
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
50 xmlns:py="http://genshi.edgewall.org/"
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
51 lang="en">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
52 ...
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
53 </html>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
54
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
55 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
56 namespace for Genshi directives is bound to the prefix “py”.
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
57
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
58 All directives can be applied as attributes, and some can also be used as
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
59 elements. The ``if`` directives for conditionals, for example, can be used in
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
60 both ways:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
61
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
62 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
63
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
64 <html xmlns="http://www.w3.org/1999/xhtml"
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
65 xmlns:py="http://genshi.edgewall.org/"
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
66 lang="en">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
67 ...
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
68 <div py:if="foo">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
69 <p>Bar</p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
70 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
71 ...
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
72 </html>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
73
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
74 This is basically equivalent to the following:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
75
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
76 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
77
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
78 <html xmlns="http://www.w3.org/1999/xhtml"
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
79 xmlns:py="http://genshi.edgewall.org/"
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
80 lang="en">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
81 ...
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
82 <py:if test="foo">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
83 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
84 <p>Bar</p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
85 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
86 </py:if>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
87 ...
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
88 </html>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
89
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
90 The rationale behind the second form is that directives do not always map
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
91 naturally to elements in the template. In such cases, the ``py:strip``
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
92 directive can be used to strip off the unwanted element, or the directive can
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
93 simply be used as an element.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
94
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
95
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
96 Conditional Sections
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
97 ====================
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
98
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
99 .. _`py:if`:
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
100
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
101 ``py:if``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
102 ---------
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
103
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
104 The element is only rendered if the expression evaluates to a truth value:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
105
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
106 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
107
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
108 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
109 <b py:if="foo">${bar}</b>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
110 </div>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
111
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
112 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
113 would produce:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
114
612
3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents: 610
diff changeset
115 .. code-block:: xml
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
116
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
117 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
118 <b>Hello</b>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
119 </div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
120
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
121 This directive can also be used as an element:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
122
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
123 .. code-block:: genshi
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
124
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
125 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
126 <py:if test="foo">
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
127 <b>${bar}</b>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
128 </py:if>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
129 </div>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
130
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
131 .. _`py:choose`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
132 .. _`py:when`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
133 .. _`py:otherwise`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
134
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
135 ``py:choose``
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
136 -------------
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
137
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
138 The ``py:choose`` directive, in combination with the directives ``py:when``
404
ee17693d2976 Fix a couple of typos in the docs. Closes #99.
cmlenz
parents: 394
diff changeset
139 and ``py:otherwise`` provides advanced conditional processing for rendering one
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
140 of several alternatives. The first matching ``py:when`` branch is rendered, or,
404
ee17693d2976 Fix a couple of typos in the docs. Closes #99.
cmlenz
parents: 394
diff changeset
141 if no ``py:when`` branch matches, the ``py:otherwise`` branch is rendered.
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
142
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
143 If the ``py:choose`` directive is empty the nested ``py:when`` directives will
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
144 be tested for truth:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
145
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
146 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
147
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
148 <div py:choose="">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
149 <span py:when="0 == 1">0</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
150 <span py:when="1 == 1">1</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
151 <span py:otherwise="">2</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
152 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
153
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
154 This would produce the following output:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
155
612
3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents: 610
diff changeset
156 .. code-block:: xml
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
157
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
158 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
159 <span>1</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
160 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
161
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
162 If the ``py:choose`` directive contains an expression the nested ``py:when``
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
163 directives will be tested for equality to the parent ``py:choose`` value:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
164
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
165 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
166
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
167 <div py:choose="1">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
168 <span py:when="0">0</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
169 <span py:when="1">1</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
170 <span py:otherwise="">2</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
171 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
172
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
173 This would produce the following output:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
174
612
3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents: 610
diff changeset
175 .. code-block:: xml
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
176
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
177 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
178 <span>1</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
179 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
180
726
85ff66a8f453 Note that py:choose and friends may be used as elements.
athomas
parents: 700
diff changeset
181 These directives can also be used as elements:
85ff66a8f453 Note that py:choose and friends may be used as elements.
athomas
parents: 700
diff changeset
182
85ff66a8f453 Note that py:choose and friends may be used as elements.
athomas
parents: 700
diff changeset
183 .. code-block:: genshi
85ff66a8f453 Note that py:choose and friends may be used as elements.
athomas
parents: 700
diff changeset
184
85ff66a8f453 Note that py:choose and friends may be used as elements.
athomas
parents: 700
diff changeset
185 <py:choose test="1">
85ff66a8f453 Note that py:choose and friends may be used as elements.
athomas
parents: 700
diff changeset
186 <py:when test="0">0</py:when>
85ff66a8f453 Note that py:choose and friends may be used as elements.
athomas
parents: 700
diff changeset
187 <py:when test="1">1</py:when>
85ff66a8f453 Note that py:choose and friends may be used as elements.
athomas
parents: 700
diff changeset
188 <py:otherwise>2</py:otherwise>
85ff66a8f453 Note that py:choose and friends may be used as elements.
athomas
parents: 700
diff changeset
189 </py:choose>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
190
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
191 Looping
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
192 =======
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
193
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
194 .. _`py:for`:
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
195
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
196 ``py:for``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
197 ----------
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
198
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
199 The element is repeated for every item in an iterable:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
200
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
201 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
202
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
203 <ul>
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
204 <li py:for="item in items">${item}</li>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
205 </ul>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
206
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
207 Given ``items=[1, 2, 3]`` in the context data, this would produce:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
208
612
3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents: 610
diff changeset
209 .. code-block:: xml
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
210
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
211 <ul>
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
212 <li>1</li><li>2</li><li>3</li>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
213 </ul>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
214
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
215 This directive can also be used as an element:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
216
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
217 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
218
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
219 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
220 <py:for each="item in items">
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
221 <li>${item}</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
222 </py:for>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
223 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
224
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
225
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
226 Snippet Reuse
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
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
229 .. _`py:def`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
230 .. _`macros`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
231
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
232 ``py:def``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
233 ----------
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
234
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
235 The ``py:def`` directive can be used to create macros, i.e. snippets of
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
236 template code that have a name and optionally some parameters, and that can be
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
237 inserted in other places:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
238
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
239 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
240
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
241 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
242 <p py:def="greeting(name)" class="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
243 Hello, ${name}!
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
244 </p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
245 ${greeting('world')}
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
246 ${greeting('everyone else')}
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
247 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
248
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
249 The above would be rendered to:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
250
612
3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents: 610
diff changeset
251 .. code-block:: xml
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
252
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
253 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
254 <p class="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
255 Hello, world!
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
256 </p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
257 <p class="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
258 Hello, everyone else!
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
259 </p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
260 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
261
394
cab6b0256019 Minor doc fixes.
cmlenz
parents: 354
diff changeset
262 If a macro doesn't require parameters, it can be defined without the
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
263 parenthesis. For example:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
264
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
265 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
266
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
267 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
268 <p py:def="greeting" class="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
269 Hello, world!
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
270 </p>
394
cab6b0256019 Minor doc fixes.
cmlenz
parents: 354
diff changeset
271 ${greeting()}
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
272 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
273
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
274 The above would be rendered to:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
275
612
3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents: 610
diff changeset
276 .. code-block:: xml
226
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 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
283
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
284 This directive can also be used as an element:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
285
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
286 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
287
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
288 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
289 <py:def function="greeting(name)">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
290 <p class="greeting">Hello, ${name}!</p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
291 </py:def>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
292 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
293
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
294
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
295 .. _Match Templates:
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
296 .. _`py:match`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
297
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
298 ``py:match``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
299 ------------
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
300
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
301 This directive defines a *match template*: given an XPath expression, it
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
302 replaces any element in the template that matches the expression with its own
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
303 content.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
304
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
305 For example, the match template defined in the following template matches any
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
306 element with the tag name “greeting”:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
307
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
308 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
309
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
310 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
311 <span py:match="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
312 Hello ${select('@name')}
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
313 </span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
314 <greeting name="Dude" />
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
315 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
316
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
317 This would result in the following output:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
318
612
3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents: 610
diff changeset
319 .. code-block:: xml
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
320
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
321 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
322 <span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
323 Hello Dude
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
324 </span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
325 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
326
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
327 Inside the body of a ``py:match`` directive, the ``select(path)`` function is
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
328 made available so that parts or all of the original element can be incorporated
451
4183fd29fa4e Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
329 in the output of the match template. See `Using XPath`_ for more information
4183fd29fa4e Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
330 about this function.
4183fd29fa4e Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
331
4183fd29fa4e Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
332 .. _`Using XPath`: streams.html#using-xpath
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
333
694
07e3f6f0ef57 Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case.
cmlenz
parents: 657
diff changeset
334 Match templates are applied both to the original markup as well to the
07e3f6f0ef57 Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case.
cmlenz
parents: 657
diff changeset
335 generated markup. The order in which they are applied depends on the order
07e3f6f0ef57 Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case.
cmlenz
parents: 657
diff changeset
336 they are declared in the template source: a match template defined after
07e3f6f0ef57 Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case.
cmlenz
parents: 657
diff changeset
337 another match template is applied to the output generated by the first match
07e3f6f0ef57 Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case.
cmlenz
parents: 657
diff changeset
338 template. The match templates basically form a pipeline.
07e3f6f0ef57 Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case.
cmlenz
parents: 657
diff changeset
339
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
340 This directive can also be used as an element:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
341
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
342 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
343
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
344 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
345 <py:match path="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
346 <span>Hello ${select('@name')}</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
347 </py:match>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
348 <greeting name="Dude" />
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
349 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
350
602
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
351 When used this way, the ``py:match`` directive can also be annotated with a
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
352 couple of optimization hints. For example, the following informs the matching
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
353 engine that the match should only be applied once:
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
354
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
355 .. code-block:: genshi
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
356
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
357 <py:match path="body" once="true">
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
358 <body py:attrs="select('@*')">
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
359 <div id="header">...</div>
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
360 ${select("*|text()")}
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
361 <div id="footer">...</div>
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
362 </body>
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
363 </py:match>
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
364
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
365 The following optimization hints are recognized:
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
366
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
367 +---------------+-----------+-----------------------------------------------+
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
368 | Attribute | Default | Description |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
369 +===============+===========+===============================================+
700
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents: 694
diff changeset
370 | ``buffer`` | ``true`` | Whether the matched content should be |
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents: 694
diff changeset
371 | | | buffered in memory. Buffering can improve |
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents: 694
diff changeset
372 | | | performance a bit at the cost of needing more |
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents: 694
diff changeset
373 | | | memory during rendering. Buffering is |
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents: 694
diff changeset
374 | | | ''required'' for match templates that contain |
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents: 694
diff changeset
375 | | | more than one invocation of the ``select()`` |
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents: 694
diff changeset
376 | | | function. If there is only one call, and the |
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents: 694
diff changeset
377 | | | matched content can potentially be very long, |
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents: 694
diff changeset
378 | | | consider disabling buffering to avoid |
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents: 694
diff changeset
379 | | | excessive memory use. |
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190.
cmlenz
parents: 694
diff changeset
380 +---------------+-----------+-----------------------------------------------+
602
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
381 | ``once`` | ``false`` | Whether the engine should stop looking for |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
382 | | | more matching elements after the first match. |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
383 | | | Use this on match templates that match |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
384 | | | elements that can only occur once in the |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
385 | | | stream, such as the ``<head>`` or ``<body>`` |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
386 | | | elements in an HTML template, or elements |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
387 | | | with a specific ID. |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
388 +---------------+-----------+-----------------------------------------------+
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
389 | ``recursive`` | ``true`` | Whether the match template should be applied |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
390 | | | to its own output. Note that ``once`` implies |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
391 | | | non-recursive behavior, so this attribute |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
392 | | | only needs to be set for match templates that |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
393 | | | don't also have ``once`` set. |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
394 +---------------+-----------+-----------------------------------------------+
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
395
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
396 .. note:: The ``py:match`` optimization hints were added in the 0.5 release. In
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
397 earlier versions, the attributes have no effect.
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
398
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
399
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
400 Variable Binding
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
401 ================
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
402
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
403 .. _`with`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
404
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
405 ``py:with``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
406 -----------
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
407
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
408 The ``py:with`` directive lets you assign expressions to variables, which can
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
409 be used to make expressions inside the directive less verbose and more
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
410 efficient. For example, if you need use the expression ``author.posts`` more
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
411 than once, and that actually results in a database query, assigning the results
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
412 to a variable using this directive would probably help.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
413
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
414 For example:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
415
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
416 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
417
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
418 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
419 <span py:with="y=7; z=x+10">$x $y $z</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
420 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
421
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
422 Given ``x=42`` in the context data, this would produce:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
423
612
3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents: 610
diff changeset
424 .. code-block:: xml
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
425
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
426 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
427 <span>42 7 52</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
428 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
429
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
430 This directive can also be used as an element:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
431
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
432 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
433
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
434 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
435 <py:with vars="y=7; z=x+10">$x $y $z</py:with>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
436 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
437
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
438 Note that if a variable of the same name already existed outside of the scope
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
439 of the ``py:with`` directive, it will **not** be overwritten. Instead, it
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
440 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
441 Effectively, this means that variables are immutable in Genshi.
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
442
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
443
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
444 Structure Manipulation
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
445 ======================
235
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:attrs`:
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:attrs``
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
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
452 This directive adds, modifies or removes attributes from the element:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
453
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
454 .. code-block:: genshi
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
455
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
456 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
457 <li py:attrs="foo">Bar</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
458 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
459
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
460 Given ``foo={'class': 'collapse'}`` in the template context, this would
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
461 produce:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
462
612
3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents: 610
diff changeset
463 .. code-block:: xml
235
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 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
466 <li class="collapse">Bar</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
467 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
468
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
469 Attributes with the value ``None`` are omitted, so given ``foo={'class': None}``
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
470 in the context for the same template this would produce:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
471
612
3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents: 610
diff changeset
472 .. code-block:: xml
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
473
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
474 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
475 <li>Bar</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
476 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
477
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
478 This directive can only be used as an attribute.
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
479
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 .. _`py:content`:
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 ``py:content``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
484 --------------
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
485
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
486 This directive replaces any nested content with the result of evaluating the
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
487 expression:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
488
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
489 .. code-block:: genshi
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
490
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
491 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
492 <li py:content="bar">Hello</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
493 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
494
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
495 Given ``bar='Bye'`` in the context data, this would produce:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
496
612
3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents: 610
diff changeset
497 .. code-block:: xml
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
498
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
499 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
500 <li>Bye</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
501 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
502
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
503 This directive can only be used as an attribute.
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
504
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
505
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
506 .. _`py:replace`:
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
507
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
508 ``py:replace``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
509 --------------
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
510
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
511 This directive replaces the element itself with the result of evaluating the
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
512 expression:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
513
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
514 .. code-block:: genshi
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
515
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
516 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
517 <span py:replace="bar">Hello</span>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
518 </div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
519
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
520 Given ``bar='Bye'`` in the context data, this would produce:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
521
612
3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents: 610
diff changeset
522 .. code-block:: xml
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
523
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
524 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
525 Bye
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
526 </div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
527
657
54964f7d2253 Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
528 This directive can also be used as an element (since version 0.5):
54964f7d2253 Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
529
54964f7d2253 Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
530 .. code-block:: genshi
54964f7d2253 Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
531
54964f7d2253 Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
532 <div>
54964f7d2253 Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
533 <py:replace value="title">Placeholder</py:replace>
54964f7d2253 Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
534 </div>
54964f7d2253 Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
535
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
536
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
537
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
538 .. _`py:strip`:
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
539
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
540 ``py:strip``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
541 ------------
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
542
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
543 This directive conditionally strips the top-level element from the output. When
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
544 the value of the ``py:strip`` attribute evaluates to ``True``, the element is
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
545 stripped from the output:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
546
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
547 .. code-block:: genshi
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
548
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
549 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
550 <div py:strip="True"><b>foo</b></div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
551 </div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
552
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
553 This would be rendered as:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
554
612
3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents: 610
diff changeset
555 .. code-block:: xml
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
556
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
557 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
558 <b>foo</b>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
559 </div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
560
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
561 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
562 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
563
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
564
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
565 .. _order:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
566
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
567 Processing Order
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
568 ================
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
569
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
570 It is possible to attach multiple directives to a single element, although not
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
571 all combinations make sense. When multiple directives are encountered, they are
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
572 processed in the following order:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
573
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
574 #. `py:def`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
575 #. `py:match`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
576 #. `py:when`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
577 #. `py:otherwise`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
578 #. `py:for`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
579 #. `py:if`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
580 #. `py:choose`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
581 #. `py:with`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
582 #. `py:replace`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
583 #. `py:content`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
584 #. `py:attrs`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
585 #. `py:strip`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
586
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
587
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
588 .. _includes:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
589
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
590 --------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
591 Includes
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
592 --------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
593
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
594 To reuse common snippets of template code, you can include other files using
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
595 XInclude_.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
596
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
597 .. _xinclude: http://www.w3.org/TR/xinclude/
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
598
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
599 For this, you need to declare the XInclude namespace (commonly bound to the
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
600 prefix “xi”) and use the ``<xi:include>`` element where you want the external
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
601 file to be pulled in:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
602
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
603 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
604
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
605 <html xmlns="http://www.w3.org/1999/xhtml"
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
606 xmlns:py="http://genshi.edgewall.org/"
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
607 xmlns:xi="http://www.w3.org/2001/XInclude">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
608 <xi:include href="base.html" />
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
609 ...
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
610 </html>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
611
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
612 Include paths are relative to the filename of the template currently being
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
613 processed. So if the example above was in the file "``myapp/index.html``"
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
614 (relative to the template search path), the XInclude processor would look for
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
615 the included file at "``myapp/base.html``". You can also use Unix-style
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
616 relative paths, for example "``../base.html``" to look in the parent directory.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
617
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
618 Any content included this way is inserted into the generated output instead of
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
619 the ``<xi:include>`` element. The included template sees the same context data.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
620 `Match templates`_ and `macros`_ in the included template are also available to
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
621 the including template after the point it was included.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
622
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
623 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
624 not what you want, you can specify fallback content that should be used if the
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
625 include fails. For example, to to make the include above fail silently, you'd
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
626 write:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
627
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
628 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
629
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
630 <xi:include href="base.html"><xi:fallback /></xi:include>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
631
273
f17bde33c1a6 Small doc fix.
cmlenz
parents: 244
diff changeset
632 See the `XInclude specification`_ for more about fallback content. Note though
f17bde33c1a6 Small doc fix.
cmlenz
parents: 244
diff changeset
633 that Genshi currently only supports a small subset of XInclude.
f17bde33c1a6 Small doc fix.
cmlenz
parents: 244
diff changeset
634
f17bde33c1a6 Small doc fix.
cmlenz
parents: 244
diff changeset
635 .. _`xinclude specification`: http://www.w3.org/TR/xinclude/
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
636
610
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
637
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
638 Dynamic Includes
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
639 ================
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
640
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
641 Incudes in Genshi are fully dynamic: Just like normal attributes, the `href`
442
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
642 attribute accepts expressions, and directives_ can be used on the
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
643 ``<xi:include />`` element just as on any other element, meaning you can do
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
644 things like conditional includes:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
645
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
646 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
647
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
648 <xi:include href="${name}.html" py:if="not in_popup"
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
649 py:for="name in ('foo', 'bar', 'baz')" />
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
650
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
651
610
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
652 Including Text Templates
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
653 ========================
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
654
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
655 The ``parse`` attribute of the ``<xi:include>`` element can be used to specify
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
656 whether the included template is an XML template or a text template (using the
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
657 new syntax added in Genshi 0.5):
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
658
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
659 .. code-block:: genshi
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
660
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
661 <xi:include href="myscript.js" parse="text" />
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
662
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
663 This example would load the ``myscript.js`` file as a ``NewTextTemplate``. See
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
664 `text templates`_ for details on the syntax of text templates.
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
665
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
666 .. _`text templates`: text-templates.html
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
667
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
668
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
669 .. _comments:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
670
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
671 --------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
672 Comments
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
673 --------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
674
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
675 Normal XML/HTML comment syntax can be used in templates:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
676
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
677 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
678
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
679 <!-- this is a comment -->
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
680
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
681 However, such comments get passed through the processing pipeline and are by
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
682 default included in the final output. If that's not desired, prefix the comment
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
683 text with an exclamation mark:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
684
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
685 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
686
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
687 <!-- !this is a comment too, but one that will be stripped from the output -->
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
688
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
689 Note that it does not matter whether there's whitespace before or after the
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
690 exclamation mark, so the above could also be written as follows:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
691
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
692 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
693
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
694 <!--! this is a comment too, but one that will be stripped from the output -->
Copyright (C) 2012-2017 Edgewall Software