Context Navigation

Markup Templates

The most important feature provided by the Markup package is a template engine.

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.

This documentation is a work in progress and as of yet rather incomplete.

Note that Markup templates are very similar to ​Kid templates, so you may want to read the awesome ​language specification for Kid for a more comprehensive guide. There exist some substantial differences between Kid and Markup, but the set of directives is basically the same (except for py:extends and py:layout, which don't exist in Markup, and py:match, which uses XPath in Markup).

Table of Contents

Template Context

Rendering a template boils down to applying one or more template files to some input data. This input data is represented as a Context? object in Markup. A context is basically a stack of dictionaries that manages the namespace scopes during processing: for example, some variable may be available under a given name inside a loop, but not outside of that loop.

Regardless of its stack behavior during templating processing, a context is usually initialized from a single dictionary:

Here the title variable in the context is accessed through a template expression, discussed below.

Template Expressions

Python expressions can be used in text and attribute values. An expression is substituted with the result of its evaluation against the template data. Expressions need to prefixed with a dollar sign ($) and usually enclosed in curly braces ({…}).

If the expression starts with a letter and contains only letters and digits, the curly braces may be omitted. In all other cases, the braces are required so that the template processors knows where the expression ends:

Template Directives

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

To use directives in a template, the namespace should 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.

py:content

This directive replaces any nested content with the result of evaluating the expression.

<ul><lipy:content="bar">Hello</li></ul>

Given bar='Bye' in the context data, this would produce:

<ul><li>Bye</li></ul>

This directive can only be used as an attribute.

py:replace

This directive replaces the element itself with the result of evaluating the expression.

<div><spanpy:replace="bar">Hello</span></div>

Given bar='Bye' in the context data, this would produce:

<div>
Bye
</div>

This directive can only be used as an attribute.

py:attrs

This directive adds, modifies or removes attributes from the element.

<ul><lipy:attrs="foo">Bar</li></ul>

Given foo={'class': 'collapse'} in the template context, this would produce:

<ul><liclass="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:

<ul><li>Bar</li></ul>

This directive can only be used as an attribute.

py:strip

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:

<div><divpy:strip="True"><b>foo</b></div></div>

This would be rendered as:

<div><b>foo</b></div>

As a shorthand, if the value of the py:strip attribute is empty, that has the same effect as using a truth value (i.e. the element is stripped).

py:if

The element is only rendered if the expression evaluates to a truth value.

<div><bpy:if="foo">${bar}</b></div>

Given the data foo=True and bar='Hello' in the template context, this would produce:

<div><b>Hello</b></div>

This directive can also be used as an element:

<div><py:iftest="foo"><b>${bar}</b></py:if></div>

py:choose / py:when / py:otherwise

This set of directives provides advanced contional processing for rendering one of several alternatives. The first matching py:when directive will be rendered or, if no py:when directive matches, the py:otherwise directive will be 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 MarkupStream for more information about this function.

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 template functions 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:include href="base.html"><xi:fallback /></xi:include>

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