Mercurial > genshi > genshi-test

annotate doc/xml-templates.txt @ 725:c2af5d7d2161 experimental-optimizer

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Note that `py:choose` and friends may be used as elements.
author athomas
date Sun, 04 May 2008 02:45:59 +0000
parents 69b3b6ca968b
children
rev   line source
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
2
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
3 ============================
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
4 Genshi XML Template Language
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
5 ============================
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
6
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
7 Genshi provides a XML-based template language that is heavily inspired by Kid_,
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
8 which in turn was inspired by a number of existing template languages, namely
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
9 XSLT_, TAL_, and PHP_.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
10
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
11 .. _kid: http://kid-templating.org/
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
12 .. _python: http://www.python.org/
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
13 .. _xslt: http://www.w3.org/TR/xslt
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
14 .. _tal: http://www.zope.org/Wikis/DevSite/Projects/ZPT/TAL
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
15 .. _php: http://www.php.net/
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
16
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
17 This document describes the template language and will be most useful as
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
18 reference to those developing Genshi XML templates. Templates are XML files of
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
19 some kind (such as XHTML) that include processing directives_ (elements or
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
20 attributes identified by a separate namespace) that affect how the template is
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
21 rendered, and template expressions that are dynamically substituted by
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
22 variable data.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
23
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
24 See `Genshi Templating Basics <templates.html>`_ for general information on
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
25 embedding Python code in templates.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
26
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
27
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
28 .. contents:: Contents
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
29 :depth: 3
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
30 .. sectnum::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
31
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
32
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
33 .. _`directives`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
34
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
35 -------------------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
36 Template Directives
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
37 -------------------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
38
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
39 Directives are elements and/or attributes in the template that are identified
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
40 by the namespace ``http://genshi.edgewall.org/``. They can affect how the
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
41 template is rendered in a number of ways: Genshi provides directives for
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
42 conditionals and looping, among others.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
43
394
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 354
diff changeset
44 To use directives in a template, the namespace must be declared, which is
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
45 usually done on the root element:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
46
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
47 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
48
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
49 <html xmlns="http://www.w3.org/1999/xhtml"
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
50 xmlns:py="http://genshi.edgewall.org/"
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
51 lang="en">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
52 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
53 </html>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
54
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
55 In this example, the default namespace is set to the XHTML namespace, and the
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
56 namespace for Genshi directives is bound to the prefix “py”.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
57
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
58 All directives can be applied as attributes, and some can also be used as
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
59 elements. The ``if`` directives for conditionals, for example, can be used in
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
60 both ways:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
61
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
62 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
63
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
64 <html xmlns="http://www.w3.org/1999/xhtml"
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
65 xmlns:py="http://genshi.edgewall.org/"
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
66 lang="en">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
67 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
68 <div py:if="foo">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
69 <p>Bar</p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
70 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
71 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
72 </html>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
73
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
74 This is basically equivalent to the following:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
75
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
76 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
77
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
78 <html xmlns="http://www.w3.org/1999/xhtml"
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
79 xmlns:py="http://genshi.edgewall.org/"
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
80 lang="en">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
81 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
82 <py:if test="foo">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
83 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
84 <p>Bar</p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
85 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
86 </py:if>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
87 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
88 </html>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
89
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
90 The rationale behind the second form is that directives do not always map
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
91 naturally to elements in the template. In such cases, the ``py:strip``
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
92 directive can be used to strip off the unwanted element, or the directive can
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
93 simply be used as an element.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
94
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
95
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
96 Conditional Sections
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
97 ====================
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
98
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
99 .. _`py:if`:
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
100
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
101 ``py:if``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
102 ---------
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
103
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
725
c2af5d7d2161 Note that `py:choose` and friends may be used as elements.
athomas
parents: 657
diff changeset
181 These directives can also be used as elements:
c2af5d7d2161 Note that `py:choose` and friends may be used as elements.
athomas
parents: 657
diff changeset
182
c2af5d7d2161 Note that `py:choose` and friends may be used as elements.
athomas
parents: 657
diff changeset
183 .. code-block:: genshi
c2af5d7d2161 Note that `py:choose` and friends may be used as elements.
athomas
parents: 657
diff changeset
184
c2af5d7d2161 Note that `py:choose` and friends may be used as elements.
athomas
parents: 657
diff changeset
185 <py:choose test="1">
c2af5d7d2161 Note that `py:choose` and friends may be used as elements.
athomas
parents: 657
diff changeset
186 <py:when test="0">0</py:when>
c2af5d7d2161 Note that `py:choose` and friends may be used as elements.
athomas
parents: 657
diff changeset
187 <py:when test="1">1</py:when>
c2af5d7d2161 Note that `py:choose` and friends may be used as elements.
athomas
parents: 657
diff changeset
188 <py:otherwise>2</py:otherwise>
c2af5d7d2161 Note that `py:choose` and friends may be used as elements.
athomas
parents: 657
diff changeset
189 </py:choose>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
190
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
191 Looping
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
192 =======
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
193
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
194 .. _`py:for`:
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
195
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
196 ``py:for``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
197 ----------
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
198
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
199 The element is repeated for every item in an iterable:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
200
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
201 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
202
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
203 <ul>
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
204 <li py:for="item in items">${item}</li>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
205 </ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
206
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
207 Given ``items=[1, 2, 3]`` in the context data, this would produce:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
208
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
209 .. code-block:: xml
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
210
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
211 <ul>
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
212 <li>1</li><li>2</li><li>3</li>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
213 </ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
214
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
215 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
216
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
217 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
218
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
219 <ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
220 <py:for each="item in items">
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
221 <li>${item}</li>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
222 </py:for>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
223 </ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
224
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
225
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
226 Snippet Reuse
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
227 =============
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
228
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
229 .. _`py:def`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
230 .. _`macros`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
231
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
232 ``py:def``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
233 ----------
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
234
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
235 The ``py:def`` directive can be used to create macros, i.e. snippets of
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
236 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
237 inserted in other places:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
238
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
239 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
240
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
241 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
242 <p py:def="greeting(name)" class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
243 Hello, ${name}!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
244 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
245 ${greeting('world')}
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
246 ${greeting('everyone else')}
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
247 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
248
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
249 The above would be rendered to:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
250
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
251 .. code-block:: xml
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
252
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
253 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
254 <p class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
255 Hello, world!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
256 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
257 <p class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
258 Hello, everyone else!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
259 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
260 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
261
394
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 354
diff changeset
262 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
263 parenthesis. For example:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
264
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
265 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
266
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
267 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
268 <p py:def="greeting" class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
269 Hello, world!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
270 </p>
394
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 354
diff changeset
271 ${greeting()}
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
272 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
273
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
274 The above would be rendered to:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
275
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
276 .. code-block:: xml
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
277
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
278 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
279 <p class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
280 Hello, world!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
281 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
282 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
283
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
284 This directive can also be used as an element:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
285
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
286 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
287
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
288 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
289 <py:def function="greeting(name)">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
290 <p class="greeting">Hello, ${name}!</p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
291 </py:def>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
292 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
293
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
294
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
295 .. _Match Templates:
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
296 .. _`py:match`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
297
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
298 ``py:match``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
299 ------------
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
300
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
301 This directive defines a *match template*: given an XPath expression, it
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
302 replaces any element in the template that matches the expression with its own
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
303 content.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
304
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
305 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
306 element with the tag name “greeting”:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
307
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
308 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
309
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
310 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
311 <span py:match="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
312 Hello ${select('@name')}
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
313 </span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
314 <greeting name="Dude" />
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
315 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
316
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
317 This would result in the following output:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
318
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
319 .. code-block:: xml
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
320
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
321 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
322 <span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
323 Hello Dude
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
324 </span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
325 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
326
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
327 Inside the body of a ``py:match`` directive, the ``select(path)`` function is
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
328 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
329 in the output of the match template. See `Using XPath`_ for more information
bcc1d6c67a2f Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
330 about this function.
bcc1d6c67a2f Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
331
bcc1d6c67a2f Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
332 .. _`Using XPath`: streams.html#using-xpath
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
333
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
334 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
335
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
336 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
337
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
338 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
339 <py:match path="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
340 <span>Hello ${select('@name')}</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
341 </py:match>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
342 <greeting name="Dude" />
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
343 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
344
602
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
345 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
346 couple of optimization hints. For example, the following informs the matching
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
347 engine that the match should only be applied once:
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
348
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
349 .. code-block:: genshi
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
350
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
351 <py:match path="body" once="true">
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
352 <body py:attrs="select('@*')">
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
353 <div id="header">...</div>
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
354 ${select("*|text()")}
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
355 <div id="footer">...</div>
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
356 </body>
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
357 </py:match>
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
358
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
359 The following optimization hints are recognized:
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
360
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
361 +---------------+-----------+-----------------------------------------------+
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
362 | Attribute | Default | Description |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
363 +===============+===========+===============================================+
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
364 | ``once`` | ``false`` | Whether the engine should stop looking for |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
365 | | | more matching elements after the first match. |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
366 | | | Use this on match templates that match |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
367 | | | elements that can only occur once in the |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
368 | | | stream, such as the ``<head>`` or ``<body>`` |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
369 | | | elements in an HTML template, or elements |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
370 | | | with a specific ID. |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
371 +---------------+-----------+-----------------------------------------------+
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
372 | ``recursive`` | ``true`` | Whether the match template should be applied |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
373 | | | to its own output. Note that ``once`` implies |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
374 | | | non-recursive behavior, so this attribute |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
375 | | | only needs to be set for match templates that |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
376 | | | don't also have ``once`` set. |
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
377 +---------------+-----------+-----------------------------------------------+
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
378
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
379 .. 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
380 earlier versions, the attributes have no effect.
509b3a5e765e Add runtime optimization hints for match templates.
cmlenz
parents: 510
diff changeset
381
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
382
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
383 Variable Binding
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
384 ================
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
385
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
386 .. _`with`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
387
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
388 ``py:with``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
389 -----------
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
390
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
391 The ``py:with`` directive lets you assign expressions to variables, which can
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
392 be used to make expressions inside the directive less verbose and more
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
393 efficient. For example, if you need use the expression ``author.posts`` more
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
394 than once, and that actually results in a database query, assigning the results
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
395 to a variable using this directive would probably help.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
396
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
397 For example:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
398
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
399 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
400
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
401 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
402 <span py:with="y=7; z=x+10">$x $y $z</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
403 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
404
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
405 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
406
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
407 .. code-block:: xml
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
408
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
409 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
410 <span>42 7 52</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
411 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
412
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
413 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
414
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
415 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
416
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
417 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
418 <py:with vars="y=7; z=x+10">$x $y $z</py:with>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
419 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
420
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
421 Note that if a variable of the same name already existed outside of the scope
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
422 of the ``py:with`` directive, it will **not** be overwritten. Instead, it
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
423 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
424 Effectively, this means that variables are immutable in Genshi.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
425
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
426
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
427 Structure Manipulation
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
428 ======================
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 .. _`py:attrs`:
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
431
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
432 ``py:attrs``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
433 ------------
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
434
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
435 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
436
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
437 .. code-block:: genshi
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 py:attrs="foo">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 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
444 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 class="collapse">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 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
453 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
454
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
455 .. code-block:: xml
235
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 <ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
458 <li>Bar</li>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
459 </ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
460
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
461 This directive can only be used as an attribute.
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
462
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
463
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
464 .. _`py:content`:
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
465
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
466 ``py:content``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
467 --------------
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
468
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
469 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
470 expression:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
471
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
472 .. code-block:: genshi
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
473
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
474 <ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
475 <li py:content="bar">Hello</li>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
476 </ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
477
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
478 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
479
612
09de73cae3d5 Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents: 610
diff changeset
480 .. code-block:: xml
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
481
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
482 <ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
483 <li>Bye</li>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
484 </ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
485
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
486 This directive can only be used as an attribute.
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
487
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
488
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
489 .. _`py:replace`:
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
490
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
491 ``py:replace``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
492 --------------
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
493
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
494 This directive replaces 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
495 expression:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
496
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
497 .. code-block:: genshi
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
498
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
499 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
500 <span py:replace="bar">Hello</span>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
501 </div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
502
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
503 Given ``bar='Bye'`` in the context data, this would produce:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
504
612
09de73cae3d5 Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`.
cmlenz
parents: 610
diff changeset
505 .. code-block:: xml
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
506
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
507 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
508 Bye
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
509 </div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
510
657
69b3b6ca968b Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
511 This directive can also be used as an element (since version 0.5):
69b3b6ca968b Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
512
69b3b6ca968b Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
513 .. code-block:: genshi
69b3b6ca968b Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
514
69b3b6ca968b Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
515 <div>
69b3b6ca968b Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
516 <py:replace value="title">Placeholder</py:replace>
69b3b6ca968b Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
517 </div>
69b3b6ca968b Allow use of py:replace as element. Closes #144.
cmlenz
parents: 612
diff changeset
518
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
519
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
520
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
521 .. _`py:strip`:
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
522
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
523 ``py:strip``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
524 ------------
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
525
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
526 This directive conditionally strips the top-level element from the output. When
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
527 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
528 stripped from the output:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
529
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
530 .. code-block:: genshi
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
531
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
532 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
533 <div py:strip="True"><b>foo</b></div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
534 </div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
535
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
536 This would be rendered as:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
537
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
538 .. code-block:: xml
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
539
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
540 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
541 <b>foo</b>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
542 </div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
543
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
544 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
545 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
546
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
547
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
548 .. _order:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
549
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
550 Processing Order
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
551 ================
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
552
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
553 It is possible to attach multiple directives to a single element, although not
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
554 all combinations make sense. When multiple directives are encountered, they are
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
555 processed in the following order:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
556
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
557 #. `py:def`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
558 #. `py:match`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
559 #. `py:when`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
560 #. `py:otherwise`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
561 #. `py:for`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
562 #. `py:if`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
563 #. `py:choose`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
564 #. `py:with`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
565 #. `py:replace`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
566 #. `py:content`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
567 #. `py:attrs`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
568 #. `py:strip`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
569
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
570
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
571 .. _includes:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
572
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
573 --------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
574 Includes
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
575 --------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
576
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
577 To reuse common snippets of template code, you can include other files using
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
578 XInclude_.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
579
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
580 .. _xinclude: http://www.w3.org/TR/xinclude/
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
581
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
582 For this, you need to declare the XInclude namespace (commonly bound to the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
583 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
584 file to be pulled in:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
585
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
586 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
587
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
588 <html xmlns="http://www.w3.org/1999/xhtml"
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
589 xmlns:py="http://genshi.edgewall.org/"
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
590 xmlns:xi="http://www.w3.org/2001/XInclude">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
591 <xi:include href="base.html" />
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
592 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
593 </html>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
594
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
595 Include paths are relative to the filename of the template currently being
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
596 processed. So if the example above was in the file "``myapp/index.html``"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
597 (relative to the template search path), the XInclude processor would look for
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
598 the included file at "``myapp/base.html``". You can also use Unix-style
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
599 relative paths, for example "``../base.html``" to look in the parent directory.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
600
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
601 Any content included this way is inserted into the generated output instead of
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
602 the ``<xi:include>`` element. The included template sees the same context data.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
603 `Match templates`_ and `macros`_ in the included template are also available to
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
604 the including template after the point it was included.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
605
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
606 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
607 not what you want, you can specify fallback content that should be used if the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
608 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
609 write:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
610
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
611 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
612
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
613 <xi:include href="base.html"><xi:fallback /></xi:include>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
614
273
4afa86e2ad83 Small doc fix.
cmlenz
parents: 244
diff changeset
615 See the `XInclude specification`_ for more about fallback content. Note though
4afa86e2ad83 Small doc fix.
cmlenz
parents: 244
diff changeset
616 that Genshi currently only supports a small subset of XInclude.
4afa86e2ad83 Small doc fix.
cmlenz
parents: 244
diff changeset
617
4afa86e2ad83 Small doc fix.
cmlenz
parents: 244
diff changeset
618 .. _`xinclude specification`: http://www.w3.org/TR/xinclude/
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
619
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
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 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
622 ================
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
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
624 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
625 attribute accepts expressions, and directives_ can be used on the
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
626 ``<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
627 things like conditional includes:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
628
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
629 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
630
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
631 <xi:include href="${name}.html" py:if="not in_popup"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
632 py:for="name in ('foo', 'bar', 'baz')" />
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
633
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
634
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
635 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
636 ========================
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
637
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
638 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
639 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
640 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
641
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
642 .. 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
643
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
644 <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
645
6a37018199fd * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101).
cmlenz
parents: 602
diff changeset
646 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
647 `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
648
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
649 .. _`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
650
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
651
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
652 .. _comments:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
653
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
654 --------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
655 Comments
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
656 --------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
657
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
658 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
659
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
660 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
661
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
662 <!-- this is a comment -->
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
663
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
664 However, such comments get passed through the processing pipeline and are by
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
665 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
666 text with an exclamation mark:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
667
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
668 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
669
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
670 <!-- !this is a comment too, but one that will be stripped from the output -->
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
671
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
672 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
673 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
674
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
675 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
676
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
677 <!--! this is a comment too, but one that will be stripped from the output -->
Copyright (C) 2012-2017 Edgewall Software