Mercurial > genshi > genshi-test
diff doc/xml-templates.txt @ 820:1837f39efd6f experimental-inline
Sync (old) experimental inline branch with trunk@1027.
| author | cmlenz |
|---|---|
| date | Wed, 11 Mar 2009 17:51:06 +0000 |
| parents | 0742f421caba |
| children |
line wrap: on
line diff
--- a/doc/xml-templates.txt +++ b/doc/xml-templates.txt @@ -42,7 +42,9 @@ conditionals and looping, among others. To use directives in a template, the namespace must be declared, which is -usually done on the root element:: +usually done on the root element: + +.. code-block:: genshi <html xmlns="http://www.w3.org/1999/xhtml" xmlns:py="http://genshi.edgewall.org/" @@ -55,7 +57,9 @@ All directives can be applied as attributes, and some can also be used as elements. The ``if`` directives for conditionals, for example, can be used in -both ways:: +both ways: + +.. code-block:: genshi <html xmlns="http://www.w3.org/1999/xhtml" xmlns:py="http://genshi.edgewall.org/" @@ -67,7 +71,9 @@ ... </html> -This is basically equivalent to the following:: +This is basically equivalent to the following: + +.. code-block:: genshi <html xmlns="http://www.w3.org/1999/xhtml" xmlns:py="http://genshi.edgewall.org/" @@ -95,20 +101,34 @@ ``py:if`` --------- -The element is only rendered if the expression evaluates to a truth value:: +The element and its content is only rendered if the expression evaluates to a +truth value: + +.. code-block:: genshi <div> <b py:if="foo">${bar}</b> </div> Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this -would produce:: +would produce: + +.. code-block:: xml <div> <b>Hello</b> </div> -This directive can also be used as an element:: +But setting ``foo=False`` would result in the following output: + +.. code-block:: xml + + <div> + </div> + +This directive can also be used as an element: + +.. code-block:: genshi <div> <py:if test="foo"> @@ -129,7 +149,9 @@ if no ``py:when`` branch matches, the ``py:otherwise`` branch is rendered. If the ``py:choose`` directive is empty the nested ``py:when`` directives will -be tested for truth:: +be tested for truth: + +.. code-block:: genshi <div py:choose=""> <span py:when="0 == 1">0</span> @@ -137,14 +159,18 @@ <span py:otherwise="">2</span> </div> -This would produce the following output:: +This would produce the following output: + +.. code-block:: xml <div> <span>1</span> </div> If the ``py:choose`` directive contains an expression the nested ``py:when`` -directives will be tested for equality to the parent ``py:choose`` value:: +directives will be tested for equality to the parent ``py:choose`` value: + +.. code-block:: genshi <div py:choose="1"> <span py:when="0">0</span> @@ -152,12 +178,23 @@ <span py:otherwise="">2</span> </div> -This would produce the following output:: +This would produce the following output: + +.. code-block:: xml <div> <span>1</span> </div> +These directives can also be used as elements: + +.. code-block:: genshi + + <py:choose test="1"> + <py:when test="0">0</py:when> + <py:when test="1">1</py:when> + <py:otherwise>2</py:otherwise> + </py:choose> Looping ======= @@ -167,19 +204,25 @@ ``py:for`` ---------- -The element is repeated for every item in an iterable:: +The element is repeated for every item in an iterable: + +.. code-block:: genshi <ul> <li py:for="item in items">${item}</li> </ul> -Given ``items=[1, 2, 3]`` in the context data, this would produce:: +Given ``items=[1, 2, 3]`` in the context data, this would produce: + +.. code-block:: xml <ul> <li>1</li><li>2</li><li>3</li> </ul> -This directive can also be used as an element:: +This directive can also be used as an element: + +.. code-block:: genshi <ul> <py:for each="item in items"> @@ -199,7 +242,9 @@ The ``py:def`` directive can be used to create macros, i.e. snippets of template code that have a name and optionally some parameters, and that can be -inserted in other places:: +inserted in other places: + +.. code-block:: genshi <div> <p py:def="greeting(name)" class="greeting"> @@ -209,7 +254,9 @@ ${greeting('everyone else')} </div> -The above would be rendered to:: +The above would be rendered to: + +.. code-block:: xml <div> <p class="greeting"> @@ -221,7 +268,9 @@ </div> If a macro doesn't require parameters, it can be defined without the -parenthesis. For example:: +parenthesis. For example: + +.. code-block:: genshi <div> <p py:def="greeting" class="greeting"> @@ -230,7 +279,9 @@ ${greeting()} </div> -The above would be rendered to:: +The above would be rendered to: + +.. code-block:: xml <div> <p class="greeting"> @@ -238,7 +289,9 @@ </p> </div> -This directive can also be used as an element:: +This directive can also be used as an element: + +.. code-block:: genshi <div> <py:def function="greeting(name)"> @@ -258,7 +311,9 @@ content. For example, the match template defined in the following template matches any -element with the tag name “greeting”:: +element with the tag name “greeting”: + +.. code-block:: genshi <div> <span py:match="greeting"> @@ -267,7 +322,9 @@ <greeting name="Dude" /> </div> -This would result in the following output:: +This would result in the following output: + +.. code-block:: xml <div> <span> @@ -282,7 +339,15 @@ .. _`Using XPath`: streams.html#using-xpath -This directive can also be used as an element:: +Match templates are applied both to the original markup as well to the +generated markup. The order in which they are applied depends on the order +they are declared in the template source: a match template defined after +another match template is applied to the output generated by the first match +template. The match templates basically form a pipeline. + +This directive can also be used as an element: + +.. code-block:: genshi <div> <py:match path="greeting"> @@ -291,6 +356,54 @@ <greeting name="Dude" /> </div> +When used this way, the ``py:match`` directive can also be annotated with a +couple of optimization hints. For example, the following informs the matching +engine that the match should only be applied once: + +.. code-block:: genshi + + <py:match path="body" once="true"> + <body py:attrs="select('@*')"> + <div id="header">...</div> + ${select("*|text()")} + <div id="footer">...</div> + </body> + </py:match> + +The following optimization hints are recognized: + ++---------------+-----------+-----------------------------------------------+ +| Attribute | Default | Description | ++===============+===========+===============================================+ +| ``buffer`` | ``true`` | Whether the matched content should be | +| | | buffered in memory. Buffering can improve | +| | | performance a bit at the cost of needing more | +| | | memory during rendering. Buffering is | +| | | ''required'' for match templates that contain | +| | | more than one invocation of the ``select()`` | +| | | function. If there is only one call, and the | +| | | matched content can potentially be very long, | +| | | consider disabling buffering to avoid | +| | | excessive memory use. | ++---------------+-----------+-----------------------------------------------+ +| ``once`` | ``false`` | Whether the engine should stop looking for | +| | | more matching elements after the first match. | +| | | Use this on match templates that match | +| | | elements that can only occur once in the | +| | | stream, such as the ``<head>`` or ``<body>`` | +| | | elements in an HTML template, or elements | +| | | with a specific ID. | ++---------------+-----------+-----------------------------------------------+ +| ``recursive`` | ``true`` | Whether the match template should be applied | +| | | to its own output. Note that ``once`` implies | +| | | non-recursive behavior, so this attribute | +| | | only needs to be set for match templates that | +| | | don't also have ``once`` set. | ++---------------+-----------+-----------------------------------------------+ + +.. note:: The ``py:match`` optimization hints were added in the 0.5 release. In + earlier versions, the attributes have no effect. + Variable Binding ================ @@ -306,19 +419,25 @@ than once, and that actually results in a database query, assigning the results to a variable using this directive would probably help. -For example:: +For example: + +.. code-block:: genshi <div> <span py:with="y=7; z=x+10">$x $y $z</span> </div> -Given ``x=42`` in the context data, this would produce:: +Given ``x=42`` in the context data, this would produce: + +.. code-block:: xml <div> <span>42 7 52</span> </div> -This directive can also be used as an element:: +This directive can also be used as an element: + +.. code-block:: genshi <div> <py:with vars="y=7; z=x+10">$x $y $z</py:with> @@ -338,21 +457,27 @@ ``py:attrs`` ------------ -This directive adds, modifies or removes attributes from the element:: +This directive adds, modifies or removes attributes from the element: + +.. code-block:: genshi <ul> <li py:attrs="foo">Bar</li> </ul> Given ``foo={'class': 'collapse'}`` in the template context, this would -produce:: +produce: + +.. code-block:: xml <ul> <li class="collapse">Bar</li> </ul> Attributes with the value ``None`` are omitted, so given ``foo={'class': None}`` -in the context for the same template this would produce:: +in the context for the same template this would produce: + +.. code-block:: xml <ul> <li>Bar</li> @@ -367,13 +492,17 @@ -------------- This directive replaces any nested content with the result of evaluating the -expression:: +expression: + +.. code-block:: genshi <ul> <li py:content="bar">Hello</li> </ul> -Given ``bar='Bye'`` in the context data, this would produce:: +Given ``bar='Bye'`` in the context data, this would produce: + +.. code-block:: xml <ul> <li>Bye</li> @@ -388,19 +517,30 @@ -------------- This directive replaces the element itself with the result of evaluating the -expression:: +expression: + +.. code-block:: genshi <div> <span py:replace="bar">Hello</span> </div> -Given ``bar='Bye'`` in the context data, this would produce:: +Given ``bar='Bye'`` in the context data, this would produce: + +.. code-block:: xml <div> Bye </div> -This directive can only be used as an attribute. +This directive can also be used as an element (since version 0.5): + +.. code-block:: genshi + + <div> + <py:replace value="title">Placeholder</py:replace> + </div> + .. _`py:strip`: @@ -410,13 +550,17 @@ This directive conditionally strips the top-level element from the output. When the value of the ``py:strip`` attribute evaluates to ``True``, the element is -stripped from the output:: +stripped from the output: + +.. code-block:: genshi <div> <div py:strip="True"><b>foo</b></div> </div> -This would be rendered as:: +This would be rendered as: + +.. code-block:: xml <div> <b>foo</b> @@ -462,7 +606,9 @@ For this, you need to declare the XInclude namespace (commonly bound to the prefix “xi”) and use the ``<xi:include>`` element where you want the external -file to be pulled in:: +file to be pulled in: + +.. code-block:: genshi <html xmlns="http://www.w3.org/1999/xhtml" xmlns:py="http://genshi.edgewall.org/" @@ -485,7 +631,9 @@ By default, an error will be raised if an included file is not found. If that's not what you want, you can specify fallback content that should be used if the include fails. For example, to to make the include above fail silently, you'd -write:: +write: + +.. code-block:: genshi <xi:include href="base.html"><xi:fallback /></xi:include> @@ -494,32 +642,61 @@ .. _`xinclude specification`: http://www.w3.org/TR/xinclude/ + +Dynamic Includes +================ + Incudes in Genshi are fully dynamic: Just like normal attributes, the `href` attribute accepts expressions, and directives_ can be used on the ``<xi:include />`` element just as on any other element, meaning you can do -things like conditional includes:: +things like conditional includes: + +.. code-block:: genshi <xi:include href="${name}.html" py:if="not in_popup" py:for="name in ('foo', 'bar', 'baz')" /> +Including Text Templates +======================== + +The ``parse`` attribute of the ``<xi:include>`` element can be used to specify +whether the included template is an XML template or a text template (using the +new syntax added in Genshi 0.5): + +.. code-block:: genshi + + <xi:include href="myscript.js" parse="text" /> + +This example would load the ``myscript.js`` file as a ``NewTextTemplate``. See +`text templates`_ for details on the syntax of text templates. + +.. _`text templates`: text-templates.html + + .. _comments: -------- Comments -------- -Normal XML/HTML comment syntax can be used in templates:: +Normal XML/HTML comment syntax can be used in templates: + +.. code-block:: genshi <!-- this is a comment --> However, such comments get passed through the processing pipeline and are by default included in the final output. If that's not desired, prefix the comment -text with an exclamation mark:: +text with an exclamation mark: + +.. code-block:: genshi <!-- !this is a comment too, but one that will be stripped from the output --> Note that it does not matter whether there's whitespace before or after the -exclamation mark, so the above could also be written as follows:: +exclamation mark, so the above could also be written as follows: + +.. code-block:: genshi <!--! this is a comment too, but one that will be stripped from the output -->