genshi/genshi-test: doc/xml-templates.txt annotate

annotate doc/xml-templates.txt @ 902:09cc3627654c experimental-inline

Sync `experimental/inline` branch with [source:trunk@1126].

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

Mercurial > genshi > genshi-test

annotate doc/xml-templates.txt @ 902:09cc3627654c experimental-inline