Context Navigation

Genshi XML Template Language

Genshi provides a XML-based template language that is heavily inspired by Kid,
which in turn was inspired by a number of existing template languages, namely
XSLT, TAL, and PHP.

This document describes the template language and will be most useful as
reference to those developing Genshi XML templates. Templates are XML files of
some kind (such as XHTML) that include processing directives (elements or
attributes identified by a separate namespace) that affect how the template is
rendered, and template expressions that are dynamically substituted by
variable data.

Directives are elements and/or attributes in the template that are identified
by the namespace http://genshi.edgewall.org/. They can affect how the
template is rendered in a number of ways: Genshi provides directives for
conditionals and looping, among others.

To use directives in a template, the namespace must be declared, which is
usually done on the root element:

The rationale behind the second form is that directives do not always map
naturally to elements in the template. In such cases, the py:strip
directive can be used to strip off the unwanted element, or the directive can
simply be used as an element.

The py:choose directive, in combination with the directives py:when
and py:otherwise provides advanced conditional processing for rendering one
of several alternatives. The first matching py:when branch is rendered, or,
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:

Inside the body of a py:match directive, the select(path) function is
made available so that parts or all of the original element can be incorporated
in the output of the match template. See Using XPath for more information
about this function.

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.

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.

The py:with directive lets you assign expressions to variables, which can
be used to make expressions inside the directive less verbose and more
efficient. For example, if you need use the expression author.posts more
than once, and that actually results in a database query, assigning the results
to a variable using this directive would probably help.

For example:

<div><spanpy:with="y=7; z=x+10">$x$y$z</span></div>

Given x=42 in the context data, this would produce:

<div><span>42 7 52</span></div>

This directive can also be used as an element:

<div><py:withvars="y=7; z=x+10">$x$y$z</py:with></div>

Note that if a variable of the same name already existed outside of the scope
of the py:with directive, it will not be overwritten. Instead, it
will have the same value it had prior to the py:with assignment.
Effectively, this means that variables are immutable in Genshi.

Include paths are relative to the filename of the template currently being
processed. So if the example above was in the file "myapp/index.html"
(relative to the template search path), the XInclude processor would look for
the included file at "myapp/base.html". You can also use Unix-style
relative paths, for example "../base.html" to look in the parent directory.

Any content included this way is inserted into the generated output instead of
the <xi:include> element. The included template sees the same context data.
Match templates and macros in the included template are also available to
the including template after the point it was included.

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:

<xi:includehref="base.html"><xi:fallback/></xi:include>

See the XInclude specification for more about fallback content. Note though
that Genshi currently only supports a small subset of XInclude.

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: