.. testsetup:: *
import kajiki
==================================
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 = '''
...
...
...
...
...
... '''
>>> 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
... ''')
>>> print Template(dict(i=4)).render()
4 is even
>>> print Template(dict(i=3)).render()
3 is odd
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
py:call
^^^^^^^^^^^^^^^^^^
Call a function, passing a block of template code as a 'lambda' parameter. Note
thnat this is a special case of calling when you wish to insert some templated text in the
expansion of a function call. In normal circumstances, you would just use `${my_function(args)}`.
>>> Template = kajiki.XMLTemplate('''
... - Quoth $speaker, ${caller(i)}
...
Nevermore $n ''')
>>> print Template(dict(sz=3)).render()
- Quoth the raven, Nevermore 0
- Quoth the raven, Nevermore 1
- Quoth the raven, Nevermore 2
py:include
^^^^^^^^^^^^^^^^^^^^^^^^
Includes the text of another template verbatim. The precise semantics of this
tag depend on the `TemplateLoader` being used, as the `TemplateLoader` is used to
parse the name of the template being included and render its contents into the
current template. For instance, with the `FileLoader`, you might use the
following:
.. code-block:: xml
whereas in the `PackageLoader` you would use
.. code-block:: xml
py:import
^^^^^^^^^^^^^^^^^^^^^^
With `py:import`, you can make the functions defined in another template available
without expanding the full template in-place. Suppose that we saved the
following template in a file `lib.xml`:
.. code-block:: xml
evenodd
Then (using the `FileLoader`) we could write a template using the `evenness`
function as follows:
.. code-block:: xml
Content Generation
=========================
py:attrs
^^^^^^^^^^^^^^
With the `py:attrs` custom attribute, you can include dynamic attributes in an
xml/html tag by passing a either a Python dict or a list of pairs:
>>> Template = kajiki.XMLTemplate('')
>>> print Template(dict(attrs={'id':'foo', 'class':'bar'})).render()
>>> print Template(dict(attrs=[('id', 'foo'), ('class', 'bar')])).render()
Any attribute values that evaluate to `None` will not be emitted in the generated
markup:
>>> Template = kajiki.XMLTemplate('')
>>> print Template(dict(attrs={'id':'foo', 'class':None})).render()
py:strip
^^^^^^^^^^^^^^
With `py:strip`, you can remove the tag to which the attribute is attached
without removing the content of the tag:
>>> Template = kajiki.XMLTemplate('')
>>> print Template().render()
Foo
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
Now we can extend "parent.xml" with "child.xml":
.. code-block:: xml
Dear $name:
${parent_block()}
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
Notice how in the child block, we have overridden both the block "body" and the
function "greet." When overriding a block, we always have access to the parent
template's block of the same name via the `parent_block()` function.
If you ever need to access the parent template itself (perhaps to call another
function), kajiki provides access to a special variable in child templates
`parent`. Likewise, if a template is being extended, the variable `child` is
available. Kajiki also provides the special variables `local` (the template
currently being defined) and `self` (the child-most template of an inheritance
chain). The following example illustrates these variables in a 3-level
inheritance hierarchy:
>>> parent = kajiki.XMLTemplate('''Header name=$name
Footer
... id() = ${id()}
... local.id() = ${local.id()}
... self.id() = ${self.id()}
... child.id() = ${child.id()}
...
parent
... ${header()}
... ${body()}
... ${footer()}
...
''')
>>> mid = kajiki.XMLTemplate('''mid''')
>>> child=kajiki.XMLTemplate('''child
...
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