Mercurial > genshi > genshi-test

annotate doc/xml-templates.txt @ 938:a5a1c9a11135 tip

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