Mercurial > genshi > genshi-test

annotate doc/xml-templates.txt @ 612:09de73cae3d5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
author cmlenz
date Wed, 29 Aug 2007 19:34:04 +0000
parents 6a37018199fd
children 69b3b6ca968b
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
510
ca7d707d51b0 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:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
105
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
106 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
107
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
108 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
109 <b py:if="foo">${bar}</b>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
110 </div>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
111
235
b3cabd49de75 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
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
113 would produce:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
114
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
115 .. code-block:: xml
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
116
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
117 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
118 <b>Hello</b>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
119 </div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
120
510
ca7d707d51b0 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:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
122
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
123 .. code-block:: genshi
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
124
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
125 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
126 <py:if test="foo">
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
127 <b>${bar}</b>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
128 </py:if>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
129 </div>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
130
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
131 .. _`py:choose`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
132 .. _`py:when`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
133 .. _`py:otherwise`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
134
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
135 ``py:choose``
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
136 -------------
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
137
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
138 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
139 and ``py:otherwise`` provides advanced conditional processing for rendering one
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
140 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
141 if no ``py:when`` branch matches, the ``py:otherwise`` branch is rendered.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
142
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
143 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
144 be tested for truth:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
145
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
146 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
147
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
148 <div py:choose="">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
149 <span py:when="0 == 1">0</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
150 <span py:when="1 == 1">1</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
151 <span py:otherwise="">2</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
152 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
153
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
154 This would produce the following output:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
155
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
156 .. code-block:: xml
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
157
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
158 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
159 <span>1</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
160 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
161
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
162 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
163 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
164
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
165 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
166
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
167 <div py:choose="1">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
168 <span py:when="0">0</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
169 <span py:when="1">1</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
170 <span py:otherwise="">2</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
171 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
172
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
173 This would produce the following output:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
174
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
175 .. code-block:: xml
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
176
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
177 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
178 <span>1</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
179 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
180
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
181
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
182 Looping
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
183 =======
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
184
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
185 .. _`py:for`:
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
186
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
187 ``py:for``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
188 ----------
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
189
510
ca7d707d51b0 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:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
191
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
192 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
193
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
194 <ul>
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
195 <li py:for="item in items">${item}</li>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
196 </ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
197
510
ca7d707d51b0 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:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
199
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
200 .. code-block:: xml
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
201
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
202 <ul>
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
203 <li>1</li><li>2</li><li>3</li>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
204 </ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
205
510
ca7d707d51b0 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:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
207
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
208 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
209
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
210 <ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
211 <py:for each="item in items">
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
212 <li>${item}</li>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
213 </py:for>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
214 </ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
215
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
216
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
217 Snippet Reuse
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
218 =============
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
219
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
220 .. _`py:def`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
221 .. _`macros`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
222
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
223 ``py:def``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
224 ----------
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
225
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
226 The ``py:def`` directive can be used to create macros, i.e. snippets of
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
227 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
228 inserted in other places:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
229
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
230 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
231
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
232 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
233 <p py:def="greeting(name)" class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
234 Hello, ${name}!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
235 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
236 ${greeting('world')}
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
237 ${greeting('everyone else')}
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
238 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
239
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
240 The above would be rendered to:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
241
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
242 .. code-block:: xml
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
243
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
244 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
245 <p class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
246 Hello, world!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
247 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
248 <p class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
249 Hello, everyone else!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
250 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
251 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
252
394
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 354
diff changeset
253 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
254 parenthesis. For example:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
255
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
256 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
257
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
258 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
259 <p py:def="greeting" class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
260 Hello, world!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
261 </p>
394
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 354
diff changeset
262 ${greeting()}
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
263 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
264
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
265 The above would be rendered to:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
266
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
267 .. code-block:: xml
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
268
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
269 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
270 <p class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
271 Hello, world!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
272 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
273 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
274
510
ca7d707d51b0 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:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
276
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
277 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
278
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
279 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
280 <py:def function="greeting(name)">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
281 <p class="greeting">Hello, ${name}!</p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
282 </py:def>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
283 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
284
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
285
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
286 .. _Match Templates:
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
287 .. _`py:match`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
288
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
289 ``py:match``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
290 ------------
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
291
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
292 This directive defines a *match template*: given an XPath expression, it
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
293 replaces any element in the template that matches the expression with its own
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
294 content.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
295
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
296 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
297 element with the tag name “greeting”:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
298
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
299 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
300
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
301 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
302 <span py:match="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
303 Hello ${select('@name')}
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
304 </span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
305 <greeting name="Dude" />
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
306 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
307
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
308 This would result in the following output:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
309
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
310 .. code-block:: xml
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
311
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
312 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
313 <span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
314 Hello Dude
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
315 </span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
316 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
317
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
318 Inside the body of a ``py:match`` directive, the ``select(path)`` function is
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
319 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
320 in the output of the match template. See `Using XPath`_ for more information
bcc1d6c67a2f Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
321 about this function.
bcc1d6c67a2f Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
322
bcc1d6c67a2f Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
323 .. _`Using XPath`: streams.html#using-xpath
226
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 directive can also be used as an element:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
326
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
327 .. code-block:: genshi
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 <py:match path="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
331 <span>Hello ${select('@name')}</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
332 </py:match>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
333 <greeting name="Dude" />
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
334 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
335
602
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
336 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
337 couple of optimization hints. For example, the following informs the matching
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
338 engine that the match should only be applied once:
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
339
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
340 .. code-block:: genshi
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
341
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
342 <py:match path="body" once="true">
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
343 <body py:attrs="select('@*')">
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
344 <div id="header">...</div>
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
345 ${select("*|text()")}
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
346 <div id="footer">...</div>
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
347 </body>
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
348 </py:match>
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
349
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
350 The following optimization hints are recognized:
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
351
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
352 +---------------+-----------+-----------------------------------------------+
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
353 | Attribute | Default | Description |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
354 +===============+===========+===============================================+
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
355 | ``once`` | ``false`` | Whether the engine should stop looking for |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
356 | | | more matching elements after the first match. |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
357 | | | Use this on match templates that match |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
358 | | | elements that can only occur once in the |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
359 | | | stream, such as the ``<head>`` or ``<body>`` |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
360 | | | elements in an HTML template, or elements |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
361 | | | with a specific ID. |
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 | ``recursive`` | ``true`` | Whether the match template should be applied |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
364 | | | to its own output. Note that ``once`` implies |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
365 | | | non-recursive behavior, so this attribute |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
366 | | | only needs to be set for match templates that |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
367 | | | don't also have ``once`` set. |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
368 +---------------+-----------+-----------------------------------------------+
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
369
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
370 .. 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
371 earlier versions, the attributes have no effect.
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
372
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
373
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
374 Variable Binding
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
375 ================
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
376
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
377 .. _`with`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
378
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
379 ``py:with``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
380 -----------
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
381
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
382 The ``py:with`` directive lets you assign expressions to variables, which can
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
383 be used to make expressions inside the directive less verbose and more
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
384 efficient. For example, if you need use the expression ``author.posts`` more
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
385 than once, and that actually results in a database query, assigning the results
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
386 to a variable using this directive would probably help.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
387
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
388 For example:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
389
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
390 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
391
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
392 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
393 <span py:with="y=7; z=x+10">$x $y $z</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
394 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
395
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
396 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
397
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
398 .. code-block:: xml
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
399
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
400 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
401 <span>42 7 52</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
402 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
403
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
404 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
405
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
406 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
407
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
408 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
409 <py:with vars="y=7; z=x+10">$x $y $z</py:with>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
410 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
411
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
412 Note that if a variable of the same name already existed outside of the scope
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
413 of the ``py:with`` directive, it will **not** be overwritten. Instead, it
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
414 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
415 Effectively, this means that variables are immutable in Genshi.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
416
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
417
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
418 Structure Manipulation
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
419 ======================
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
420
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
421 .. _`py:attrs`:
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
422
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
423 ``py:attrs``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
424 ------------
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
425
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
426 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
427
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
428 .. code-block:: genshi
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
429
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
430 <ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
431 <li py:attrs="foo">Bar</li>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
432 </ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
433
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
434 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
435 produce:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
436
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
437 .. code-block:: xml
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
438
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
439 <ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
440 <li class="collapse">Bar</li>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
441 </ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
442
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
443 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
444 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
445
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
446 .. code-block:: xml
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
447
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
448 <ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
449 <li>Bar</li>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
450 </ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
451
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
452 This directive can only be used as an attribute.
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
453
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:content`:
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:content``
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
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
460 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
461 expression:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
462
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
463 .. code-block:: genshi
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
464
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
465 <ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
466 <li py:content="bar">Hello</li>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
467 </ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
468
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
469 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
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>Bye</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 This directive can only be used as an attribute.
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
478
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
479
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
480 .. _`py:replace`:
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 ``py:replace``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
483 --------------
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
484
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
485 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
486 expression:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
487
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
488 .. code-block:: genshi
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
489
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
490 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
491 <span py:replace="bar">Hello</span>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
492 </div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
493
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
494 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
495
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
496 .. code-block:: xml
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
497
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
498 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
499 Bye
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
500 </div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
501
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
502 This directive can only be used as an attribute.
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
503
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
504
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
505 .. _`py:strip`:
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 ``py:strip``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
508 ------------
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
509
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
510 This directive conditionally strips the top-level element from the output. When
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
511 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
512 stripped from the output:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
513
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
514 .. code-block:: genshi
235
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 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
517 <div py:strip="True"><b>foo</b></div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
518 </div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
519
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
520 This would be rendered as:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
521
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
522 .. code-block:: xml
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 <b>foo</b>
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
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
528 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
529 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
530
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
531
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
532 .. _order:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
533
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
534 Processing Order
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
535 ================
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
536
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
537 It is possible to attach multiple directives to a single element, although not
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
538 all combinations make sense. When multiple directives are encountered, they are
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
539 processed in the following order:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
540
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
541 #. `py:def`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
542 #. `py:match`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
543 #. `py:when`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
544 #. `py:otherwise`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
545 #. `py:for`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
546 #. `py:if`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
547 #. `py:choose`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
548 #. `py:with`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
549 #. `py:replace`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
550 #. `py:content`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
551 #. `py:attrs`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
552 #. `py:strip`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
553
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
554
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
555 .. _includes:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
556
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
557 --------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
558 Includes
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
559 --------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
560
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
561 To reuse common snippets of template code, you can include other files using
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
562 XInclude_.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
563
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
564 .. _xinclude: http://www.w3.org/TR/xinclude/
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
565
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
566 For this, you need to declare the XInclude namespace (commonly bound to the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
567 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
568 file to be pulled in:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
569
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
570 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
571
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
572 <html xmlns="http://www.w3.org/1999/xhtml"
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
573 xmlns:py="http://genshi.edgewall.org/"
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
574 xmlns:xi="http://www.w3.org/2001/XInclude">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
575 <xi:include href="base.html" />
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
576 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
577 </html>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
578
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
579 Include paths are relative to the filename of the template currently being
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
580 processed. So if the example above was in the file "``myapp/index.html``"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
581 (relative to the template search path), the XInclude processor would look for
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
582 the included file at "``myapp/base.html``". You can also use Unix-style
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
583 relative paths, for example "``../base.html``" to look in the parent directory.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
584
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
585 Any content included this way is inserted into the generated output instead of
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
586 the ``<xi:include>`` element. The included template sees the same context data.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
587 `Match templates`_ and `macros`_ in the included template are also available to
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
588 the including template after the point it was included.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
589
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
590 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
591 not what you want, you can specify fallback content that should be used if the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
592 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
593 write:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
594
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
595 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
596
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
597 <xi:include href="base.html"><xi:fallback /></xi:include>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
598
273
4afa86e2ad83 Small doc fix.
cmlenz
parents: 244
diff changeset
599 See the `XInclude specification`_ for more about fallback content. Note though
4afa86e2ad83 Small doc fix.
cmlenz
parents: 244
diff changeset
600 that Genshi currently only supports a small subset of XInclude.
4afa86e2ad83 Small doc fix.
cmlenz
parents: 244
diff changeset
601
4afa86e2ad83 Small doc fix.
cmlenz
parents: 244
diff changeset
602 .. _`xinclude specification`: http://www.w3.org/TR/xinclude/
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
603
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
604
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
605 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
606 ================
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
607
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
608 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
609 attribute accepts expressions, and directives_ can be used on the
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
610 ``<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
611 things like conditional includes:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
612
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
613 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
614
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
615 <xi:include href="${name}.html" py:if="not in_popup"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
616 py:for="name in ('foo', 'bar', 'baz')" />
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
617
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
618
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
619 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
620 ========================
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
621
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
622 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
623 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
624 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
625
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
626 .. 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
627
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
628 <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
629
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
630 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
631 `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
632
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
633 .. _`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
634
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
635
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
636 .. _comments:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
637
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
638 --------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
639 Comments
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
640 --------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
641
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
642 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
643
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
644 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
645
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
646 <!-- this is a comment -->
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
647
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
648 However, such comments get passed through the processing pipeline and are by
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
649 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
650 text with an exclamation mark:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
651
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
652 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
653
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
654 <!-- !this is a comment too, but one that will be stripped from the output -->
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
655
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
656 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
657 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
658
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
659 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
660
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
661 <!--! this is a comment too, but one that will be stripped from the output -->
Copyright (C) 2012-2017 Edgewall Software