= 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 ''[wiki:MarkupTemplates#TemplateDirectives processing directives]'' (elements or attributes identified by a separate namespace) that affect how the template is rendered, and ''[wiki:MarkupTemplates#TemplateExpressions template expressions]'' that are dynamically substituted by variable data.
[[PageOutline(2-3, Table of Contents, inline)]]
== 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 [wiki:ApiDocs/MarkupTemplate#markup.template:Context 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 able 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:
{{{
>>> from markup.template import Context
>>> ctxt = Context(title='Hello, world!')
>>> print ctxt
[{'title': 'Hello, world!'}]
}}}
This data is then made available for use inside the template:
{{{
>>> from markup.template import Template
>>> tmpl = Template('$title
')
>>> print tmpl.generate(ctxt)
Hello, world!
}}}
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:
{{{
>>> from markup.template import Context, Template
>>> tmpl = Template('${items[0].capitalize()} item')
>>> print tmpl.generate(Context(items=['first', 'second']))
First item
}}}
Expressions support the full power of Python. In addition, it is possible to:
* access items in a dictionary using ''“dotted notation”'' (i.e. as if they were attributes)
* access attributes using item access (i.e. as if they were items in a dictionary)
{{{
>>> from markup.template import Context, Template
>>> tmpl = Template('${dict.foo}')
>>> print tmpl.generate(Context(dict={'foo': 'bar'}))
bar
}}}
== 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:
{{{
#!xml
...
}}}
In this example, the default namespace is set to the XHTML namespace, and the namespace for Markup directives is bound to the prefix “py”.
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:
{{{
#!xml
...
...
}}}
This is basically equivalent to the following:
{{{
#!xml
...
...
}}}
The rationale behind the second form is that directives not always map naturally to elements in the template. In such cases, the [wiki:MarkupTemplates#pystrip 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.
{{{
#!xml
}}}
Given `bar='Bye'` in the context data, this would produce:
{{{
#!xml
}}}
This directive can only be used as an attribute.
=== `py:replace` ===
This directive replaces the element itself with the result of evaluating the expression.
{{{
#!xml
Hello
}}}
Given `bar='Bye'` in the context data, this would produce:
{{{
#!xml
Bye
}}}
This directive can only be used as an attribute.
=== `py:attrs` ===
This directive adds, modifies or removes attributes from the element.
{{{
#!xml
}}}
Given `foo={'class': 'collapse'}` in the template context, this would produce:
{{{
#!xml
}}}
This directive can only be used as an attribute.
=== `py:strip` ===
=== `py:if` ===
The element is only rendered if the expression evaluates to a truth value.
=== `py:choose` / `py:when` / `py:otherwise` ===
This set of directives provides advanced contional processing: one of several alternatives is rendered depending on which of the `py:when` directives evaluates to a truth value.
{{{
#!xml
0
1
2
}}}
This would produce the following output:
{{{
#!xml
1
}}}
=== `py:for` ===
The element is repeated for every item in an iterable:
{{{
#!xml
}}}
Given `items=[1, 2, 3]` in the context data, this would produce:
{{{
#!xml
}}}
This directive can also be used as an element:
{{{
#!xml
}}}
=== `py:def` ===
=== `py:match` ===
== Template Includes ==
To reuse common snippets of template code, you can include other files using [http://www.w3.org/TR/xinclude/ XInclude].
For this, you need to declare the XInclude namespace (commonly bound to the prefix "xi") and use the `` element where you want the external file to be pulled in:
{{{
...
}}}
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.
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:
{{{
}}}
See the [http://www.w3.org/TR/xinclude/ XInclude specification] for more about fallback content. Note though that Markup currently only supports a small subset of XInclude.