= 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'' identified by the namespace `http://markup.edgewall.org/` and ''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('<h1>$title</h1>')
>>> print tmpl.generate(ctxt)
<h1>Hello, world!</h1>
}}}

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('<em>${items[0].capitalize()} item</em>')
>>> print tmpl.generate(Context(items=['first', 'second']))
<em>First item</em>
}}}

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('<em>${dict.foo}</em>')
>>> print tmpl.generate(Context(dict={'foo': 'bar'}))
<em>bar</em>
}}}

== Template Directives ==

=== `py:content` ===

=== `py:replace` ===

=== `py:attrs` ===

=== `py:if` ===

=== `py:choose` / `py:when` / `py:otherwise` ===

=== `py:for` ===

=== `py:def` ===

=== `py:match` ===

== Template Includes ==