==================================
Kajiki XML Templates
==================================
Kajiki provides a full-featured XML-based template engine that guarantees
well-formed output when generating HTML and XML. This document describes that
language. Templates are XML files that include template directives that control
how the template is rendered and expressions that are substituted into the
generated text at render time.
Please see :doc:`templating-basics` for general information on embedding Python
code in templates.
Output Modes
=========================
Although Kajiki XML templates must be well-formed XML documents, Kajiki is capable of
rendering HTML or XML. By default, Kajiki will inspect the doctype of the
template to determine how to render:
>>> tpl_text = '''
...
...
...
...
...
... '''
>>> import kajiki
>>> Template = kajiki.XMLTemplate(tpl_text)
>>> print(Template().render().strip())
>>> # If we want to override the detected type, we can pass a 'mode' param
>>> Template = kajiki.XMLTemplate(tpl_text, mode='xml')
>>> print(Template().render().strip())
>>> # We can also omit the generated DOCTYPE by specifying the template
>>> # is a fragment
>>> Template = kajiki.XMLTemplate(tpl_text, mode='xml', is_fragment=True)
>>> print(Template().render().strip())
.. note::
In Kajiki, you can use normal XML comments, and the comments will exist in the
generated markup. If you wish the comments to be removed before rendering the
document, you can begin the comment with the syntax `
... ''')
>>> print(Template().render())
Basic Expressions
=========================
Let's start with a hello world template:
>>> Template = kajiki.XMLTemplate('Hello, $name!
')
>>> print(Template(dict(name='world')).render())
Hello, world!
By default, the $-syntax picks up any identifiers following it, as well as any
periods. If you want something more explicit, use the extended expression form
as follows:
>>> Template = kajiki.XMLTemplate('Hello, 2+2 is ${2+2}
')
>>> print(Template().render())
Hello, 2+2 is 4
If you wish to include a literal $, simply double it:
>>> Template = kajiki.XMLTemplate('The price is $$${price}
')
>>> print(Template(dict(price='5.00')).render())
The price is $5.00
You can also include expressions in template attributes:
>>> Template = kajiki.XMLTemplate('Bar
')
>>> print(Template(dict(foo='baz')).render())
Bar
Control Flow
============
Kajiki provides several directives that affect the rendering of a template. This
section describes the various directives. Directives in text templates can
either appear as special attributes on tags prefixed by `py:` or as standalone
tags whose tagname is prefixed by `py:`.
py:if, py:else
^^^^^^^^^^^^^^^
Only render the enclosed content if the expression evaluates to a truthy value:
>>> Template = kajiki.XMLTemplate('')
>>> print(Template(dict(foo=True)).render())
bar
>>> print(Template(dict(foo=False)).render())
baz
>>> Template = kajiki.XMLTemplate('bar
')
>>> print(Template(dict(foo=True)).render())
bar
>>> print(Template(dict(foo=False)).render())
py:switch, py:case, py:else
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Perform multiple tests to render one of several alternatives. The first matching
`case` is rendered, and if no `case` matches, the `else` branch is rendered:
>>> Template = kajiki.XMLTemplate('''
... $i is
... even
... odd
...
4 is even
>>> print(Template(dict(i=3)).render())
3 is odd
py:match, py:case
^^^^^^^^^^^^^^^^^
Similar to ``py:switch`` this makes use of `PEP622 `_
Structural Pattern Matching:
>>> import sys, pytest
>>> if sys.version_info < (3, 10): pytest.skip('pep622 unsupported')
>>> Template = kajiki.XMLTemplate('''
... $i is
... even
... odd
...
4 is even
>>> print(Template(dict(i=3)).render())
3 is odd
.. note::
``py:match`` compiles directly to Python's ``match`` syntax, and will
therefore not work on versions less than 3.10. Only use this syntax if your
project targets Python 3.10 or newer.
py:for
^^^^^^^^^^^^^
Repeatedly render the content for each item in an iterable:
>>> Template = kajiki.XMLTemplate('''''')
>>> print(Template(dict(sz=3)).render())
py:def
^^^^^^^^^^^^^^
Defines a function that can be used elsewhere in the template:
>>> Template = kajiki.XMLTemplate('''evenodd
... - $x is ${evenness(x)}
...
''')
>>> print(Template(dict(sz=3)).render())
- 0 is even
- 1 is odd
- 2 is even
... - Quoth $speaker, ${caller(i)}
...
Nevermore $n
- Quoth the raven, Nevermore 0
- Quoth the raven, Nevermore 1
- Quoth the raven, Nevermore 2
Foo
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:content
^^^^^^^^^^^^^^
With `py:content`, you can remove the tag to which the attribute is attached
without removing the content of the tag:
>>> Template = kajiki.XMLTemplate('')
>>> print(Template(dict(content="Foo")).render())
Foo
py:replace
^^^^^^^^^^^^^^
With `py:replace`, you can replace the entire tag to which the document is
attached and its children:
>>> Template = kajiki.XMLTemplate('')
>>> print(Template(dict(content="Foo")).render())
Foo
Inheritance (py:extends, py:block)
===================================
Kajiki supports a concept of inheritance whereby child templates can extend
parent templates, replacing their "methods" (functions) and "blocks" (to be defined below).
For instance, consider the following template "parent.xml":
.. code-block:: xml
Hello, $name!
Sincerely,
$name
${greet(to)}
It was good seeing you last Friday.
Thanks for the gift!
${sign(from_)}
This would render to something similar to the following (assuming a context of
`dict(to=Mark, from_=Rick)`:
.. code-block:: xml
Hello, Mark!
It was good seeing you last friday.
Thanks for the gift!
Sincerely,
Rick
And don't forget you owe me money!
Rendering this template would then give us:
.. code-block:: xml
Dear, Mark:
It was good seeing you last friday.
Thanks for the gift!
And don't forget you owe me money!
Sincerely,
Rick
Header name=$name
Footer
... id() = ${id()}
... local.id() = ${local.id()}
... self.id() = ${self.id()}
... child.id() = ${child.id()}
...
parent
... ${header()}
... ${body()}
... ${footer()}
...
...
Child Body
... ${parent.body()}
... ''')
>>> loader = kajiki.MockLoader({
... 'parent.html':parent,
... 'mid.html':mid,
... 'child.html':child})
>>> Template = loader.import_('child.html')
>>> print(Template(dict(name='Rick')).render())
Header name=Rick
Child Body
id() = child
local.id() = parent
self.id() = child
child.id() = mid
Footer
Summary of Directives
=====================
========== ====================== ============================ ==========================================================
Directive Usable as an attribute Usable as a separate element When used as a separate element, requires attributes named
========== ====================== ============================ ==========================================================
py:if ✅ ✅ test
py:else ✅ ✅
py:switch ❌ ✅ test
py:match ❌ ✅ on
py:case ✅ ✅ value or match (for usage with py:switch or py:match)
py:for ✅ ✅ each
py:def ✅ ✅ function
py:call ❌ ✅ args, function
py:include ❌ ✅ href
py:import ❌ ✅ href
py:with ✅ ✅ vars
py:attrs ✅ ❌
py:strip ✅ ❌
py:content ✅ ❌
py:replace ✅ ✅ value
py:extends ❌ ✅ href
py:block ✅ ✅ name
========== ====================== ============================ ==========================================================
Built-in functions
==================
The following functions are available by default in template code,
in addition to the standard built-ins that are available to all Python code.
defined(name)
^^^^^^^^^^^^^
This function determines whether a variable of the specified name exists in the context data, and returns True if it does.
When would you use it? Well, suppose you tried the following template snippet:
$user.name
If you don't pass, from your python code, a "user" variable to the template,
the above code will fail with this exception:
``NameError: global name 'user' is not defined``. This is undesired!
Following Genshi, Kajiki offers the ``defined()`` function to make
that condition possible, so you can write this:
$user.name
literal(text)
^^^^^^^^^^^^^
All good templating languages escape text by default to avoid certain attacks.
But sometimes you have an HTML snippet that you wish to include in a page,
and you know the HTML is safe.
The literal() function marks a given string as being safe for inclusion,
meaning it will not be escaped in the serialization stage. Use this with care,
as not escaping a user-provided string may allow malicious users to open
your web site to cross-site scripting attacks. Example:
${literal(name_of_the_variable_containing_the_html)}
Kajiki is a reimplementation of most of Genshi and, since Genshi has a
``Markup()`` function for the same purpose, we provide ``Markup()`` as a
synonym, too.
value_of(name, default=None)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This function returns the value of the variable with the specified name
if such a variable is defined, and returns the value of the default parameter
if no such variable is defined.
Genshi has this, too. Example::
${explanation}
In the above example, the div will only appear in the output if the
``explanation`` variable exists in the context and has a truish value.
(Remember in Python, None and the empty string are not truish, they are
evaluated as False.)
Tips on writing your templates
==============================
Kajiki takes XML as input, with the exception that it recognizes HTML entities
in addition to XML entities. (HTML has many more entities than XML;
for instance, XML does not define `` ``).
If your template contains complex content in ``
This is not necessary when you are writing HTML because HTML defines that the
content of ``