Mercurial > genshi > mirror

annotate doc/xml-templates.txt @ 703:af57b12e3dd2 experimental-match-fastpaths

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
author aflett
date Mon, 31 Mar 2008 22:47:50 +0000
parents 54964f7d2253
children ea46fb523485
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
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
181
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
182 Looping
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
183 =======
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
184
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
185 .. _`py:for`:
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
186
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
187 ``py:for``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
188 ----------
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
189
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
190 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
191
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
192 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
193
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
194 <ul>
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
195 <li py:for="item in items">${item}</li>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
196 </ul>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
197
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
198 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
199
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
200 .. code-block:: xml
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
201
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
202 <ul>
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
203 <li>1</li><li>2</li><li>3</li>
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
204 </ul>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
205
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
206 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
207
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
208 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
209
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
210 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
211 <py:for each="item in items">
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
212 <li>${item}</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
213 </py:for>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
214 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
215
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
216
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
217 Snippet Reuse
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
218 =============
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
219
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
220 .. _`py:def`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
221 .. _`macros`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
222
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
223 ``py:def``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
224 ----------
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
225
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
226 The ``py:def`` directive can be used to create macros, i.e. snippets of
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
227 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
228 inserted in other places:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
229
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
230 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
231
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
232 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
233 <p py:def="greeting(name)" class="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
234 Hello, ${name}!
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
235 </p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
236 ${greeting('world')}
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
237 ${greeting('everyone else')}
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
238 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
239
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
240 The above would be rendered to:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
241
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
242 .. code-block:: xml
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
243
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
244 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
245 <p class="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
246 Hello, world!
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
247 </p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
248 <p class="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
249 Hello, everyone else!
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
250 </p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
251 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
252
394
cab6b0256019 Minor doc fixes.
cmlenz
parents: 354
diff changeset
253 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
254 parenthesis. For example:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
255
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
256 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
257
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
258 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
259 <p py:def="greeting" class="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
260 Hello, world!
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
261 </p>
394
cab6b0256019 Minor doc fixes.
cmlenz
parents: 354
diff changeset
262 ${greeting()}
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
263 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
264
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
265 The above would be rendered to:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
266
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
267 .. code-block:: xml
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
268
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
269 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
270 <p class="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
271 Hello, world!
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
272 </p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
273 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
274
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
275 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
276
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
277 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
278
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
279 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
280 <py:def function="greeting(name)">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
281 <p class="greeting">Hello, ${name}!</p>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
282 </py:def>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
283 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
284
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
285
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
286 .. _Match Templates:
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
287 .. _`py:match`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
288
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
289 ``py:match``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
290 ------------
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
291
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
292 This directive defines a *match template*: given an XPath expression, it
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
293 replaces any element in the template that matches the expression with its own
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
294 content.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
295
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
296 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
297 element with the tag name “greeting”:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
298
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
299 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
300
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
301 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
302 <span py:match="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
303 Hello ${select('@name')}
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
304 </span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
305 <greeting name="Dude" />
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
306 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
307
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
308 This would result in the following output:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
309
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
310 .. code-block:: xml
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
311
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
312 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
313 <span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
314 Hello Dude
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
315 </span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
316 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
317
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
318 Inside the body of a ``py:match`` directive, the ``select(path)`` function is
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
319 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
320 in the output of the match template. See `Using XPath`_ for more information
4183fd29fa4e Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
321 about this function.
4183fd29fa4e Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
322
4183fd29fa4e Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
323 .. _`Using XPath`: streams.html#using-xpath
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
324
703
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
325 Match templates are applied both to the original markup as well to the
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
326 generated markup. The order in which they are applied depends on the order
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
327 they are declared in the template source: a match template defined after
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
328 another match template is applied to the output generated by the first match
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
329 template. The match templates basically form a pipeline.
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
330
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
331 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
332
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
333 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
334
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
335 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
336 <py:match path="greeting">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
337 <span>Hello ${select('@name')}</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
338 </py:match>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
339 <greeting name="Dude" />
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
340 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
341
602
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
342 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
343 couple of optimization hints. For example, the following informs the matching
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
344 engine that the match should only be applied once:
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
345
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
346 .. code-block:: genshi
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
347
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
348 <py:match path="body" once="true">
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
349 <body py:attrs="select('@*')">
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
350 <div id="header">...</div>
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
351 ${select("*|text()")}
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
352 <div id="footer">...</div>
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
353 </body>
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
354 </py:match>
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
355
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
356 The following optimization hints are recognized:
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
357
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
358 +---------------+-----------+-----------------------------------------------+
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
359 | Attribute | Default | Description |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
360 +===============+===========+===============================================+
703
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
361 | ``buffer`` | ``true`` | Whether the matched content should be |
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
362 | | | buffered in memory. Buffering can improve |
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
363 | | | performance a bit at the cost of needing more |
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
364 | | | memory during rendering. Buffering is |
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
365 | | | ''required'' for match templates that contain |
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
366 | | | more than one invocation of the ``select()`` |
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
367 | | | function. If there is only one call, and the |
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
368 | | | matched content can potentially be very long, |
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
369 | | | consider disabling buffering to avoid |
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
370 | | | excessive memory use. |
af57b12e3dd2 merge in trunk up through r818 - fundamentally changed the way MatchSet works, but actually is more consistent now
aflett
parents: 657
diff changeset
371 +---------------+-----------+-----------------------------------------------+
602
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
372 | ``once`` | ``false`` | Whether the engine should stop looking for |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
373 | | | more matching elements after the first match. |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
374 | | | Use this on match templates that match |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
375 | | | elements that can only occur once in the |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
376 | | | stream, such as the ``<head>`` or ``<body>`` |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
377 | | | elements in an HTML template, or elements |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
378 | | | with a specific ID. |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
379 +---------------+-----------+-----------------------------------------------+
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
380 | ``recursive`` | ``true`` | Whether the match template should be applied |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
381 | | | to its own output. Note that ``once`` implies |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
382 | | | non-recursive behavior, so this attribute |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
383 | | | only needs to be set for match templates that |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
384 | | | don't also have ``once`` set. |
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
385 +---------------+-----------+-----------------------------------------------+
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
386
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
387 .. 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
388 earlier versions, the attributes have no effect.
d7b957e92ea9 Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
389
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
390
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
391 Variable Binding
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
392 ================
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
393
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
394 .. _`with`:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
395
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
396 ``py:with``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
397 -----------
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
398
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
399 The ``py:with`` directive lets you assign expressions to variables, which can
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
400 be used to make expressions inside the directive less verbose and more
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
401 efficient. For example, if you need use the expression ``author.posts`` more
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
402 than once, and that actually results in a database query, assigning the results
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
403 to a variable using this directive would probably help.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
404
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
405 For example:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
406
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
407 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
408
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
409 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
410 <span py:with="y=7; z=x+10">$x $y $z</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
411 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
412
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
413 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
414
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
415 .. code-block:: xml
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
416
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
417 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
418 <span>42 7 52</span>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
419 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
420
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
421 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
422
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
423 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
424
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
425 <div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
426 <py:with vars="y=7; z=x+10">$x $y $z</py:with>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
427 </div>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
428
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
429 Note that if a variable of the same name already existed outside of the scope
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
430 of the ``py:with`` directive, it will **not** be overwritten. Instead, it
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
431 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
432 Effectively, this means that variables are immutable in Genshi.
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
433
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
434
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
435 Structure Manipulation
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
436 ======================
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
437
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
438 .. _`py:attrs`:
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
439
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
440 ``py:attrs``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
441 ------------
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
442
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
443 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
444
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
445 .. code-block:: genshi
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 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
448 <li py:attrs="foo">Bar</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
449 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
450
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
451 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
452 produce:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
453
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
454 .. code-block:: xml
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 class="collapse">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 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
461 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
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>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 This directive can only be used as an attribute.
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
470
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
471
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
472 .. _`py:content`:
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 ``py:content``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
475 --------------
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
476
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
477 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
478 expression:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
479
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
480 .. code-block:: genshi
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
481
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
482 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
483 <li py:content="bar">Hello</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
484 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
485
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
486 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
487
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
488 .. code-block:: xml
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
489
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
490 <ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
491 <li>Bye</li>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
492 </ul>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
493
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
494 This directive can only be used as an attribute.
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
495
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
496
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
497 .. _`py:replace`:
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 ``py:replace``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
500 --------------
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
501
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
502 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
503 expression:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
504
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
505 .. code-block:: genshi
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
506
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
507 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
508 <span py:replace="bar">Hello</span>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
509 </div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
510
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
511 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
512
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
513 .. code-block:: xml
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
514
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
515 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
516 Bye
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
517 </div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
518
657
54964f7d2253 Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
519 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
520
54964f7d2253 Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
521 .. code-block:: genshi
54964f7d2253 Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
522
54964f7d2253 Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
523 <div>
54964f7d2253 Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
524 <py:replace value="title">Placeholder</py:replace>
54964f7d2253 Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
525 </div>
54964f7d2253 Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
526
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
527
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
528
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
529 .. _`py:strip`:
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
530
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
531 ``py:strip``
237
670f543fd8c2 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
532 ------------
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
533
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
534 This directive conditionally strips the top-level element from the output. When
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
535 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
536 stripped from the output:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
537
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
538 .. code-block:: genshi
235
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 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
541 <div py:strip="True"><b>foo</b></div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
542 </div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
543
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
544 This would be rendered as:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
545
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
546 .. code-block:: xml
235
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
547
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
548 <div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
549 <b>foo</b>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
550 </div>
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
551
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
552 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
553 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
554
41107d1ba1c8 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
555
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
556 .. _order:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
557
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
558 Processing Order
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
559 ================
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
560
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
561 It is possible to attach multiple directives to a single element, although not
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
562 all combinations make sense. When multiple directives are encountered, they are
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
563 processed in the following order:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
564
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
565 #. `py:def`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
566 #. `py:match`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
567 #. `py:when`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
568 #. `py:otherwise`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
569 #. `py:for`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
570 #. `py:if`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
571 #. `py:choose`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
572 #. `py:with`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
573 #. `py:replace`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
574 #. `py:content`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
575 #. `py:attrs`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
576 #. `py:strip`_
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
577
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
578
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
579 .. _includes:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
580
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
581 --------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
582 Includes
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
583 --------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
584
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
585 To reuse common snippets of template code, you can include other files using
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
586 XInclude_.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
587
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
588 .. _xinclude: http://www.w3.org/TR/xinclude/
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
589
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
590 For this, you need to declare the XInclude namespace (commonly bound to the
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
591 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
592 file to be pulled in:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
593
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
594 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
595
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
596 <html xmlns="http://www.w3.org/1999/xhtml"
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
597 xmlns:py="http://genshi.edgewall.org/"
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
598 xmlns:xi="http://www.w3.org/2001/XInclude">
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
599 <xi:include href="base.html" />
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
600 ...
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
601 </html>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
602
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
603 Include paths are relative to the filename of the template currently being
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
604 processed. So if the example above was in the file "``myapp/index.html``"
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
605 (relative to the template search path), the XInclude processor would look for
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
606 the included file at "``myapp/base.html``". You can also use Unix-style
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
607 relative paths, for example "``../base.html``" to look in the parent directory.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
608
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
609 Any content included this way is inserted into the generated output instead of
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
610 the ``<xi:include>`` element. The included template sees the same context data.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
611 `Match templates`_ and `macros`_ in the included template are also available to
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
612 the including template after the point it was included.
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
613
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
614 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
615 not what you want, you can specify fallback content that should be used if the
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
616 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
617 write:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
618
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
619 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
620
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
621 <xi:include href="base.html"><xi:fallback /></xi:include>
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
622
273
f17bde33c1a6 Small doc fix.
cmlenz
parents: 244
diff changeset
623 See the `XInclude specification`_ for more about fallback content. Note though
f17bde33c1a6 Small doc fix.
cmlenz
parents: 244
diff changeset
624 that Genshi currently only supports a small subset of XInclude.
f17bde33c1a6 Small doc fix.
cmlenz
parents: 244
diff changeset
625
f17bde33c1a6 Small doc fix.
cmlenz
parents: 244
diff changeset
626 .. _`xinclude specification`: http://www.w3.org/TR/xinclude/
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
627
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
628
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
629 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
630 ================
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
631
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
632 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
633 attribute accepts expressions, and directives_ can be used on the
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
634 ``<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
635 things like conditional includes:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
636
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
637 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
638
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
639 <xi:include href="${name}.html" py:if="not in_popup"
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
640 py:for="name in ('foo', 'bar', 'baz')" />
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
641
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
642
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
643 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
644 ========================
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
645
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
646 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
647 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
648 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
649
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
650 .. 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
651
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 <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
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 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
655 `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
656
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 .. _`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
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
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
660 .. _comments:
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
661
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
662 --------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
663 Comments
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
664 --------
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
665
510
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
666 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
667
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
668 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
669
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
670 <!-- this is a comment -->
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
671
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
672 However, such comments get passed through the processing pipeline and are by
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
673 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
674 text with an exclamation mark:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
675
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
676 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
677
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
678 <!-- !this is a comment too, but one that will be stripped from the output -->
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
679
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
680 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
681 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
682
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
683 .. code-block:: genshi
226
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
684
4d8a9e03b23d Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
685 <!--! this is a comment too, but one that will be stripped from the output -->
Copyright (C) 2012-2017 Edgewall Software