Mercurial > genshi > genshi-test

annotate doc/xml-templates.txt @ 226:09f869a98149

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add reStructuredText documentation files.
author cmlenz
date Fri, 08 Sep 2006 08:44:31 +0000
parents
children 24757b771651
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 ============================
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
4 Markup XML Template Language
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
5 ============================
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
6
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
7 Markup provides a simple XML-based template language that is heavily inspired
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
8 by Kid_, which in turn was inspired by a number of existing template languages,
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
9 namely XSLT_, TAL_, and PHP_.
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
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
18 reference to those developing Markup templates. Templates are XML files of some
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
19 kind (such as XHTML) that include processing directives_ (elements or
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
20 attributes identified by a separate namespace) that affect how the template is
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
21 rendered, and template expressions_ that are dynamically substituted by
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
22 variable data.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
23
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
24
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
25 .. contents:: Contents
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
26 :depth: 3
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
27 .. sectnum::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
28
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
29 ----------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
30 Python API
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 The Python code required for templating with Markup is generally based on the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
34 following pattern:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
35
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
36 * Attain a ``Template`` object from a string or file object containing the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
37 template XML source. This can either be done directly, or through a
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
38 ``TemplateLoader`` instance.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
39 * Call the ``generate()`` method of the template, passing any data that should
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
40 be made available to the template as keyword arguments.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
41 * Serialize the resulting stream using its ``render()`` method.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
42
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
43 For example::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
44
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
45 from markup.template import Template
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
46
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
47 tmpl = Template('<h1>$title</h1>')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
48 stream = tmpl.generate(title='Hello, world!')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
49 print stream.render('xhtml')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
50
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
51 That code would produce the following output::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
52
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
53 <h1>Hello, world!</h1>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
54
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
55 However, if you want includes_ to work, you should attain the template instance
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
56 through a ``TemplateLoader``, and load the template from a file::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
57
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
58 from markup.template import TemplateLoader
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
59
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
60 loader = TemplateLoader([templates_dir])
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
61 tmpl = loader.load('test.html')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
62 stream = tmpl.generate(title='Hello, world!')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
63 print stream.render('xhtml')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
64
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
65
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
66 .. _`expressions`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
67
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
68 --------------------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
69 Template Expressions
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
70 --------------------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
71
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
72 Python_ expressions can be used in text and attribute values. An expression is
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
73 substituted with the result of its evaluation against the template data.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
74 Expressions need to prefixed with a dollar sign (``$``) and usually enclosed in
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
75 curly braces (``{…}``).
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
76
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
77 If the expression starts with a letter and contains only letters and digits,
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
78 the curly braces may be omitted. In all other cases, the braces are required so
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
79 that the template processors knows where the expression ends::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
80
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
81 >>> from markup.template import Context, Template
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
82 >>> tmpl = Template('<em>${items[0].capitalize()} item</em>')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
83 >>> print tmpl.generate(Context(items=['first', 'second']))
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
84 <em>First item</em>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
85
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
86 Expressions support the full power of Python. In addition, it is possible to
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
87 access items in a dictionary using “dotted notation” (i.e. as if they were
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
88 attributes), and vice-versa (i.e. access attributes as if they were items in a
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
89 dictionary)::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
90
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
91 >>> from markup.template import Context, Template
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
92 >>> tmpl = Template('<em>${dict.foo}</em>')
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
93 >>> print tmpl.generate(Context(dict={'foo': 'bar'}))
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
94 <em>bar</em>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
95
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
96
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
97 .. _`directives`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
98
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
99 -------------------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
100 Template Directives
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
101 -------------------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
102
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
103 Directives are elements and/or attributes in the template that are identified
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
104 by the namespace ``http://markup.edgewall.org/``. They can affect how the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
105 template is rendered in a number of ways: Markup provides directives for
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
106 conditionals and looping, among others.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
107
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
108 To use directives in a template, the namespace should be declared, which is
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
109 usually done on the root element::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
110
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
111 <html xmlns="http://www.w3.org/1999/xhtml"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
112 xmlns:py="http://markup.edgewall.org/"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
113 lang="en">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
114 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
115 </html>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
116
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
117 In this example, the default namespace is set to the XHTML namespace, and the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
118 namespace for Markup directives is bound to the prefix “py”.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
119
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
120 All directives can be applied as attributes, and some can also be used as
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
121 elements. The ``if`` directives for conditionals, for example, can be used in
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
122 both ways::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
123
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
124 <html xmlns="http://www.w3.org/1999/xhtml"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
125 xmlns:py="http://markup.edgewall.org/"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
126 lang="en">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
127 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
128 <div py:if="foo">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
129 <p>Bar</p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
130 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
131 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
132 </html>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
133
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
134 This is basically equivalent to the following::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
135
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
136 <html xmlns="http://www.w3.org/1999/xhtml"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
137 xmlns:py="http://markup.edgewall.org/"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
138 lang="en">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
139 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
140 <py:if test="foo">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
141 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
142 <p>Bar</p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
143 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
144 </py:if>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
145 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
146 </html>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
147
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
148 The rationale behind the second form is that directives do not always map
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
149 naturally to elements in the template. In such cases, the ``py:strip``
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
150 directive can be used to strip off the unwanted element, or the directive can
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
151 simply be used as an element.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
152
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
153
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
154 Available Directives
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
155 ====================
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
156
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
157
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
158 .. _`py:attrs`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
159
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
160 ``py:attrs``
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
161 ------------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
162
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
163 This directive adds, modifies or removes attributes from the element::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
164
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
165 <ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
166 <li py:attrs="foo">Bar</li>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
167 </ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
168
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
169 Given ``foo={'class': 'collapse'}`` in the template context, this would
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
170 produce::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
171
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
172 <ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
173 <li class="collapse">Bar</li>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
174 </ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
175
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
176 Attributes with the value ``None`` are omitted, so given ``foo={'class': None}``
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
177 in the context for the same template this would produce::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
178
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
179 <ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
180 <li>Bar</li>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
181 </ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
182
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
183 This directive can only be used as an attribute.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
184
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
185
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
186 .. _`py:choose`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
187 .. _`py:when`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
188 .. _`py:otherwise`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
189
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
190 ``py:choose`` / ``py:when`` / ``py:otherwise``
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
191 ----------------------------------------------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
192
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
193 This set of directives provides advanced contional processing for rendering one
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
194 of several alternatives. The first matching ``py:when`` branch is rendered, or,
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
195 if no ``py:when`` branch matches, the ``py:otherwise`` branch is be rendered.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
196
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
197 If the ``py:choose`` directive is empty the nested ``py:when`` directives will
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
198 be tested for truth::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
199
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
200 <div py:choose="">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
201 <span py:when="0 == 1">0</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
202 <span py:when="1 == 1">1</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
203 <span py:otherwise="">2</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
204 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
205
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
206 This would produce the following output::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
207
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
208 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
209 <span>1</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
210 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
211
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
212 If the ``py:choose`` directive contains an expression the nested ``py:when``
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
213 directives will be tested for equality to the parent ``py:choose`` value::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
214
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
215 <div py:choose="1">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
216 <span py:when="0">0</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
217 <span py:when="1">1</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
218 <span py:otherwise="">2</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
219 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
220
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
221 This would produce the following output::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
222
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
223 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
224 <span>1</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
225 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
227
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
228 .. _`py:content`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
229
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
230 ``py:content``
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
231 --------------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
232
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
233 This directive replaces any nested content with the result of evaluating the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
234 expression::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
235
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
236 <ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
237 <li py:content="bar">Hello</li>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
238 </ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
239
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
240 Given ``bar='Bye'`` in the context data, this would produce::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
241
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
242 <ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
243 <li>Bye</li>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
244 </ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
245
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
246 This directive can only be used as an attribute.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
247
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
248
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
249 .. _`py:def`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
250 .. _`macros`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
251
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
252 ``py:def``
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
253 ----------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
254
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
255 The ``py:def`` directive can be used to create macros, i.e. snippets of
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
256 template code that have a name and optionally some parameters, and that can be
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
257 inserted in other places::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
258
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
259 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
260 <p py:def="greeting(name)" class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
261 Hello, ${name}!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
262 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
263 ${greeting('world')}
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
264 ${greeting('everyone else')}
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
265 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
266
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
267 The above would be rendered to::
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 <p class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
274 Hello, everyone else!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
275 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
276 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
277
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
278 If a macro doesn't require parameters, it can be defined as well as called
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
279 without the parenthesis. For example::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
280
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
281 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
282 <p py:def="greeting" class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
283 Hello, world!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
284 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
285 ${greeting}
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
286 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
287
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
288 The above would be rendered to::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
289
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
290 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
291 <p class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
292 Hello, world!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
293 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
294 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
295
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
296 This directive can also be used as an element::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
297
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
298 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
299 <py:def function="greeting(name)">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
300 <p class="greeting">Hello, ${name}!</p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
301 </py:def>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
302 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
303
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
304
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
305 .. _`py:for`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
306
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
307 ``py:for``
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
308 ----------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
309
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
310 The element is repeated for every item in an iterable::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
311
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
312 <ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
313 <li py:for="item in items">${item}</li>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
314 </ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
315
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
316 Given ``items=[1, 2, 3]`` in the context data, this would produce::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
317
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
318 <ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
319 <li>1</li><li>2</li><li>3</li>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
320 </ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
321
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
322 This directive can also be used as an element::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
323
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
324 <ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
325 <py:for each="item in items">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
326 <li>${item}</li>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
327 </py:for>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
328 </ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
329
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
330
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
331 .. _`py:if`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
332
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
333 ``py:if``
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
334 ------------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
335
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
336 The element is only rendered if the expression evaluates to a truth value::
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 <b py:if="foo">${bar}</b>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
340 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
341
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
342 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
343 would produce::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
344
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
345 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
346 <b>Hello</b>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
347 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
348
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
349 This directive can also be used as an element::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
350
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
351 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
352 <py:if test="foo">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
353 <b>${bar}</b>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
354 </py:if>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
355 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
356
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
357
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
358 .. _`py:match`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
359 .. _Match Templates:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
360
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
361 ``py:match``
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
362 ------------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
363
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
364 This directive defines a *match template*: given an XPath expression, it
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
365 replaces any element in the template that matches the expression with its own
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
366 content.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
367
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
368 For example, the match template defined in the following template matches any
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
369 element with the tag name “greeting”::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
370
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
371 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
372 <span py:match="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
373 Hello ${select('@name')}
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
374 </span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
375 <greeting name="Dude" />
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
376 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
377
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
378 This would result in the following output::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
379
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
380 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
381 <span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
382 Hello Dude
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
383 </span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
384 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
385
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
386 Inside the body of a ``py:match`` directive, the ``select(path)`` function is
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
387 made available so that parts or all of the original element can be incorporated
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
388 in the output of the match template. See [wiki:MarkupStream#UsingXPath] for
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
389 more information about this function.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
390
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
391 This directive can also be used as an element::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
392
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
393 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
394 <py:match path="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
395 <span>Hello ${select('@name')}</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
396 </py:match>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
397 <greeting name="Dude" />
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
398 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
399
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
400
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
401 .. _`py:replace`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
402
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
403 ``py:replace``
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
404 --------------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
405
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
406 This directive replaces the element itself with the result of evaluating the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
407 expression::
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 py:replace="bar">Hello</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
411 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
412
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
413 Given ``bar='Bye'`` in the context data, this would produce::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
414
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
415 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
416 Bye
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
417 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
418
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
419 This directive can only be used as an attribute.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
420
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
421
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
422 .. _`py:strip`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
423
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
424 ``py:strip``
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
425 ------------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
426
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
427 This directive conditionally strips the top-level element from the output. When
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
428 the value of the ``py:strip`` attribute evaluates to ``True``, the element is
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
429 stripped from the output::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
430
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
431 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
432 <div py:strip="True"><b>foo</b></div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
433 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
434
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
435 This would be rendered as::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
436
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
437 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
438 <b>foo</b>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
439 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
440
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
441 As a shorthand, if the value of the ``py:strip`` attribute is empty, that has
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
442 the same effect as using a truth value (i.e. the element is stripped).
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
443
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
444
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
445 .. _`with`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
446
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
447 ``py:with``
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
448 -----------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
449
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
450 The ``py:with`` directive lets you assign expressions to variables, which can
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
451 be used to make expressions inside the directive less verbose and more
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
452 efficient. For example, if you need use the expression ``author.posts`` more
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
453 than once, and that actually results in a database query, assigning the results
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
454 to a variable using this directive would probably help.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
455
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
456 For example::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
457
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
458 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
459 <span py:with="y=7; z=x+10">$x $y $z</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
460 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
461
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
462 Given ``x=42`` in the context data, this would produce::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
463
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
464 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
465 <span>42 7 52</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
466 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
467
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
468 This directive can also be used as an element::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
469
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
470 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
471 <py:with vars="y=7; z=x+10">$x $y $z</py:with>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
472 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
473
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
474 Note that if a variable of the same name already existed outside of the scope
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
475 of the ``py:with`` directive, it will **not** be overwritten. Instead, it
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
476 will have the same value it had prior to the ``py:with`` assignment.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
477 Effectively, this means that variables are immutable in Markup.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
478
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
479
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
480 .. _order:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
481
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
482 Processing Order
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
483 ================
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
484
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
485 It is possible to attach multiple directives to a single element, although not
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
486 all combinations make sense. When multiple directives are encountered, they are
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
487 processed in the following order:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
488
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
489 #. `py:def`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
490 #. `py:match`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
491 #. `py:when`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
492 #. `py:otherwise`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
493 #. `py:for`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
494 #. `py:if`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
495 #. `py:choose`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
496 #. `py:with`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
497 #. `py:replace`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
498 #. `py:content`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
499 #. `py:attrs`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
500 #. `py:strip`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
501
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
502
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
503 .. _includes:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
504
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
505 --------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
506 Includes
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
507 --------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
508
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
509 To reuse common snippets of template code, you can include other files using
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
510 XInclude_.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
511
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
512 .. _xinclude: http://www.w3.org/TR/xinclude/
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
513
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
514 For this, you need to declare the XInclude namespace (commonly bound to the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
515 prefix “xi”) and use the ``<xi:include>`` element where you want the external
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
516 file to be pulled in::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
517
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
518 <html xmlns="http://www.w3.org/1999/xhtml"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
519 xmlns:py="http://markup.edgewall.org/"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
520 xmlns:xi="http://www.w3.org/2001/XInclude">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
521 <xi:include href="base.html" />
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
522 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
523 </html>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
524
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
525 Include paths are relative to the filename of the template currently being
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
526 processed. So if the example above was in the file "``myapp/index.html``"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
527 (relative to the template search path), the XInclude processor would look for
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
528 the included file at "``myapp/base.html``". You can also use Unix-style
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
529 relative paths, for example "``../base.html``" to look in the parent directory.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
530
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
531 Any content included this way is inserted into the generated output instead of
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
532 the ``<xi:include>`` element. The included template sees the same context data.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
533 `Match templates`_ and `macros`_ in the included template are also available to
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
534 the including template after the point it was included.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
535
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
536 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
537 not what you want, you can specify fallback content that should be used if the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
538 include fails. For example, to to make the include above fail silently, you'd
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
539 write:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
540
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
541 <xi:include href="base.html"><xi:fallback /></xi:include>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
542
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
543 See the XInclude_ for more about fallback content. Note though that Markup
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
544 currently only supports a small subset of XInclude.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
545
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
546 Incudes in Markup are fully dynamic: Just like normal attributes, the `href`
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
547 attribute accepts expressions_, and directives_ can be used on the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
548 ``<xi:include />`` element just as on any other element, meaning you can do
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
549 things like conditional includes::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
550
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
551 <xi:include href="${name}.html" py:if="not in_popup"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
552 py:for="name in ('foo', 'bar', 'baz')" />
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 .. _comments:
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 Comments
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 Normal XML/HTML comment syntax can be used in templates::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
562
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
563 <!-- this is a comment -->
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
564
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
565 However, such comments get passed through the processing pipeline and are by
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
566 default included in the final output. If that's not desired, prefix the comment
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
567 text with an exclamation mark::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
568
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
569 <!-- !this is a comment too, but one that will be stripped from the output -->
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
570
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
571 Note that it does not matter whether there's whitespace before or after the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
572 exclamation mark, so the above could also be written as follows::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
573
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
574 <!--! this is a comment too, but one that will be stripped from the output -->
Copyright (C) 2012-2017 Edgewall Software