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

annotate doc/xml-templates.txt @ 820:9755836bb396 experimental-inline

Sync (old) experimental inline branch with trunk@1027.

author	cmlenz
date	Wed, 11 Mar 2009 17:51:06 +0000
parents	3eb30e4ece8c
children

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

annotate doc/xml-templates.txt @ 820:9755836bb396 experimental-inline