.. 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('
barbaz
') >>> 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
''') >>> print Template(dict(sz=3)).render()
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('''
Nevermore $n
''') >>> print Template(dict(sz=3)).render()
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
  • $i is ${lib.evenness(i)}
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('
Foo
') >>> 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