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

annotate doc/xml-templates.txt @ 803:f8ca33751678 trunk

`for` loops in template code blocks should not establish their own locals block. Closes #259.

author	cmlenz
date	Thu, 05 Mar 2009 10:05:12 +0000
parents	25d6cd05746c
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
442 97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: 429 diff changeset	21 rendered, and template expressions that are dynamically substituted by
226 4d8a9e03b23d Add reStructuredText documentation files. cmlenz parents: diff changeset	22 variable data.
4d8a9e03b23d Add reStructuredText documentation files. cmlenz parents: diff changeset	23
442 97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: 429 diff changeset	24 See `Genshi Templating Basics <templates.html>`_ for general information on
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: 429 diff changeset	25 embedding Python code in templates.
97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: 429 diff changeset	26
226 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
394 cab6b0256019 Minor doc fixes. cmlenz parents: 354 diff changeset	44 To use directives in a template, the namespace must be declared, which is
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	45 usually done on the root element:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	46
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	60 both ways:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	61
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	74 This is basically equivalent to the following:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	75
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
746 25d6cd05746c Clarify description of the `py:if` directive. cmlenz parents: 726 diff changeset	104 The element and its content is only rendered if the expression evaluates to a
25d6cd05746c Clarify description of the `py:if` directive. cmlenz parents: 726 diff changeset	105 truth value:
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	106
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	114 would produce:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	115
612 3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`. cmlenz parents: 610 diff changeset	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
746 25d6cd05746c Clarify description of the `py:if` directive. cmlenz parents: 726 diff changeset	122 But setting ``foo=False`` would result in the following output:
25d6cd05746c Clarify description of the `py:if` directive. cmlenz parents: 726 diff changeset	123
25d6cd05746c Clarify description of the `py:if` directive. cmlenz parents: 726 diff changeset	124 .. code-block:: xml
25d6cd05746c Clarify description of the `py:if` directive. cmlenz parents: 726 diff changeset	125
25d6cd05746c Clarify description of the `py:if` directive. cmlenz parents: 726 diff changeset	126 <div>
25d6cd05746c Clarify description of the `py:if` directive. cmlenz parents: 726 diff changeset	127 </div>
25d6cd05746c Clarify description of the `py:if` directive. cmlenz parents: 726 diff changeset	128
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	129 This directive can also be used as an element:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	130
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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``
404 ee17693d2976 Fix a couple of typos in the docs. Closes #99. cmlenz parents: 394 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,
404 ee17693d2976 Fix a couple of typos in the docs. Closes #99. cmlenz parents: 394 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	152 be tested for truth:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	153
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	162 This would produce the following output:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	163
612 3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`. cmlenz parents: 610 diff changeset	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``
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	171 directives will be tested for equality to the parent ``py:choose`` value:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	172
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	181 This would produce the following output:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	182
612 3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`. cmlenz parents: 610 diff changeset	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
726 85ff66a8f453 Note that py:choose and friends may be used as elements. athomas parents: 700 diff changeset	189 These directives can also be used as elements:
85ff66a8f453 Note that py:choose and friends may be used as elements. athomas parents: 700 diff changeset	190
85ff66a8f453 Note that py:choose and friends may be used as elements. athomas parents: 700 diff changeset	191 .. code-block:: genshi
85ff66a8f453 Note that py:choose and friends may be used as elements. athomas parents: 700 diff changeset	192
85ff66a8f453 Note that py:choose and friends may be used as elements. athomas parents: 700 diff changeset	193 <py:choose test="1">
85ff66a8f453 Note that py:choose and friends may be used as elements. athomas parents: 700 diff changeset	194 <py:when test="0">0</py:when>
85ff66a8f453 Note that py:choose and friends may be used as elements. athomas parents: 700 diff changeset	195 <py:when test="1">1</py:when>
85ff66a8f453 Note that py:choose and friends may be used as elements. athomas parents: 700 diff changeset	196 <py:otherwise>2</py:otherwise>
85ff66a8f453 Note that py:choose and friends may be used as elements. athomas parents: 700 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	207 The element is repeated for every item in an iterable:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	208
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	215 Given ``items=[1, 2, 3]`` in the context data, this would produce:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	216
612 3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`. cmlenz parents: 610 diff changeset	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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	223 This directive can also be used as an element:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	224
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	245 inserted in other places:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	246
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	257 The above would be rendered to:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	258
612 3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`. cmlenz parents: 610 diff changeset	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
394 cab6b0256019 Minor doc fixes. cmlenz parents: 354 diff changeset	270 If a macro doesn't require parameters, it can be defined without the
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	271 parenthesis. For example:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	272
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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>
394 cab6b0256019 Minor doc fixes. cmlenz parents: 354 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	282 The above would be rendered to:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	283
612 3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`. cmlenz parents: 610 diff changeset	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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	292 This directive can also be used as an element:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	293
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	314 element with the tag name “greeting”:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	315
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	325 This would result in the following output:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	326
612 3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`. cmlenz parents: 610 diff changeset	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
451 4183fd29fa4e Fix broken link in documentation. cmlenz parents: 442 diff changeset	337 in the output of the match template. See `Using XPath`_ for more information
4183fd29fa4e Fix broken link in documentation. cmlenz parents: 442 diff changeset	338 about this function.
4183fd29fa4e Fix broken link in documentation. cmlenz parents: 442 diff changeset	339
4183fd29fa4e Fix broken link in documentation. cmlenz parents: 442 diff changeset	340 .. _`Using XPath`: streams.html#using-xpath
226 4d8a9e03b23d Add reStructuredText documentation files. cmlenz parents: diff changeset	341
694 07e3f6f0ef57 Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case. cmlenz parents: 657 diff changeset	342 Match templates are applied both to the original markup as well to the
07e3f6f0ef57 Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case. cmlenz parents: 657 diff changeset	343 generated markup. The order in which they are applied depends on the order
07e3f6f0ef57 Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case. cmlenz parents: 657 diff changeset	344 they are declared in the template source: a match template defined after
07e3f6f0ef57 Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case. cmlenz parents: 657 diff changeset	345 another match template is applied to the output generated by the first match
07e3f6f0ef57 Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case. cmlenz parents: 657 diff changeset	346 template. The match templates basically form a pipeline.
07e3f6f0ef57 Match templates are now applied in a more controlled fashion: in the order they are declared in the template source, all match templates up to (and including) the matching template itself are applied to the matched content, whereas the match templates declared after the matching template are only applied to the generated content. Fixes #186. Many thanks to Matt Chaput for reporting the problem and providing a test case. cmlenz parents: 657 diff changeset	347
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	348 This directive can also be used as an element:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	349
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
602 d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	359 When used this way, the ``py:match`` directive can also be annotated with a
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	360 couple of optimization hints. For example, the following informs the matching
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	361 engine that the match should only be applied once:
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	362
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	363 .. code-block:: genshi
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	364
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	365 <py:match path="body" once="true">
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	366 <body py:attrs="select('@*')">
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	367 <div id="header">...</div>
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	368 ${select("*\|text()")}
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	369 <div id="footer">...</div>
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	370 </body>
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	371 </py:match>
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	372
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	373 The following optimization hints are recognized:
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	374
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	375 +---------------+-----------+-----------------------------------------------+
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	376 \| Attribute \| Default \| Description \|
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	377 +===============+===========+===============================================+
700 08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190. cmlenz parents: 694 diff changeset	378 \| ``buffer`` \| ``true`` \| Whether the matched content should be \|
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190. cmlenz parents: 694 diff changeset	379 \| \| \| buffered in memory. Buffering can improve \|
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190. cmlenz parents: 694 diff changeset	380 \| \| \| performance a bit at the cost of needing more \|
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190. cmlenz parents: 694 diff changeset	381 \| \| \| memory during rendering. Buffering is \|
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190. cmlenz parents: 694 diff changeset	382 \| \| \| ''required'' for match templates that contain \|
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190. cmlenz parents: 694 diff changeset	383 \| \| \| more than one invocation of the ``select()`` \|
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190. cmlenz parents: 694 diff changeset	384 \| \| \| function. If there is only one call, and the \|
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190. cmlenz parents: 694 diff changeset	385 \| \| \| matched content can potentially be very long, \|
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190. cmlenz parents: 694 diff changeset	386 \| \| \| consider disabling buffering to avoid \|
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190. cmlenz parents: 694 diff changeset	387 \| \| \| excessive memory use. \|
08f22328303d Add option for unbuffered match template processing, which could cause excessive memory usage. Closes #190. cmlenz parents: 694 diff changeset	388 +---------------+-----------+-----------------------------------------------+
602 d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	389 \| ``once`` \| ``false`` \| Whether the engine should stop looking for \|
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	390 \| \| \| more matching elements after the first match. \|
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	391 \| \| \| Use this on match templates that match \|
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	392 \| \| \| elements that can only occur once in the \|
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	393 \| \| \| stream, such as the ``<head>`` or ``<body>`` \|
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	394 \| \| \| elements in an HTML template, or elements \|
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	395 \| \| \| with a specific ID. \|
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	396 +---------------+-----------+-----------------------------------------------+
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	397 \| ``recursive`` \| ``true`` \| Whether the match template should be applied \|
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	398 \| \| \| to its own output. Note that ``once`` implies \|
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	399 \| \| \| non-recursive behavior, so this attribute \|
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	400 \| \| \| only needs to be set for match templates that \|
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	401 \| \| \| don't also have ``once`` set. \|
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	402 +---------------+-----------+-----------------------------------------------+
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	403
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	404 .. note:: The ``py:match`` optimization hints were added in the 0.5 release. In
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 diff changeset	405 earlier versions, the attributes have no effect.
d7b957e92ea9 Add runtime optimization hints for match templates. cmlenz parents: 510 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	422 For example:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	423
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	430 Given ``x=42`` in the context data, this would produce:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	431
612 3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`. cmlenz parents: 610 diff changeset	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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	438 This directive can also be used as an element:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	439
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	460 This directive adds, modifies or removes attributes from the element:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	461
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	469 produce:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	470
612 3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`. cmlenz parents: 610 diff changeset	471 .. code-block:: xml
235 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}``
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	478 in the context for the same template this would produce:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	479
612 3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`. cmlenz parents: 610 diff changeset	480 .. code-block:: xml
235 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	495 expression:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	496
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	503 Given ``bar='Bye'`` in the context data, this would produce:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	504
612 3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`. cmlenz parents: 610 diff changeset	505 .. code-block:: xml
235 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	520 expression:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	521
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	528 Given ``bar='Bye'`` in the context data, this would produce:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	529
612 3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`. cmlenz parents: 610 diff changeset	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
657 54964f7d2253 Allow use of py:replace as element. Closes #144. cmlenz parents: 612 diff changeset	536 This directive can also be used as an element (since version 0.5):
54964f7d2253 Allow use of py:replace as element. Closes #144. cmlenz parents: 612 diff changeset	537
54964f7d2253 Allow use of py:replace as element. Closes #144. cmlenz parents: 612 diff changeset	538 .. code-block:: genshi
54964f7d2253 Allow use of py:replace as element. Closes #144. cmlenz parents: 612 diff changeset	539
54964f7d2253 Allow use of py:replace as element. Closes #144. cmlenz parents: 612 diff changeset	540 <div>
54964f7d2253 Allow use of py:replace as element. Closes #144. cmlenz parents: 612 diff changeset	541 <py:replace value="title">Placeholder</py:replace>
54964f7d2253 Allow use of py:replace as element. Closes #144. cmlenz parents: 612 diff changeset	542 </div>
54964f7d2253 Allow use of py:replace as element. Closes #144. cmlenz parents: 612 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	553 stripped from the output:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	554
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	561 This would be rendered as:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	562
612 3d2909fe1dda Using `html` code-blocks for examples isn't so nice when viewing the docs over Trac, so change them to `xml`. cmlenz parents: 610 diff changeset	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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	609 file to be pulled in:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	610
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	634 write:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	635
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
610 5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	645
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	646 Dynamic Includes
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	647 ================
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	648
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`
442 97544725bb7f Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option. cmlenz parents: 429 diff changeset	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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	652 things like conditional includes:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	653
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
610 5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	660 Including Text Templates
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	661 ========================
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	662
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	663 The ``parse`` attribute of the ``<xi:include>`` element can be used to specify
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	664 whether the included template is an XML template or a text template (using the
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	665 new syntax added in Genshi 0.5):
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	666
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	667 .. code-block:: genshi
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	668
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	669 <xi:include href="myscript.js" parse="text" />
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	670
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	671 This example would load the ``myscript.js`` file as a ``NewTextTemplate``. See
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	672 `text templates`_ for details on the syntax of text templates.
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	673
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	674 .. _`text templates`: text-templates.html
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	675
5e358de79e4c * XInclude elements in markup templates now support the `parse` attribute; when set to "xml" (the default), the include is processed as before, but when set to "text", the included template is parsed as a text template using the new syntax (ticket #101). cmlenz parents: 602 diff changeset	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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	683 Normal XML/HTML comment syntax can be used in templates:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	684
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	691 text with an exclamation mark:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	692
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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
510 1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	698 exclamation mark, so the above could also be written as follows:
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 diff changeset	699
1bdccd3bda00 Use syntax highlighting on all the other doc pages, too. cmlenz parents: 451 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 @ 803:f8ca33751678 trunk