5.1   Identifier Shortcut ($name)

For simple expressions consisting entirely variable names and object access operators (.), the curly braces may be omitted:

<a href="http://example.com/$page" title="$title">
   Dots are allowed too: $object.another.attribute
</a>

However, it is good practice to use the curly brace form as it sets the substitution off from the other text a bit more providing a stronger visual clue as to what's going on.

5.2   Escaping ($$)

$$ is an escape. $${bla} will output ${bla}.

6.1   XML() function

Python Expression substitution, py:content, and py:replace encode strings as text. That is, text is encoded according to the rules of the XML specification, which includes, among other things, replacing the literal characters < and & with their encoded counterparts (&lt; &amp;). If you have XML stored as a string and want it to be output as XML and not encoded text, you need to pass the string to the XML function.

For example, let's say there is a function, hello, that returns XML data that should be embedded in template output (let's say it returns <hello>world</hello>). Consider the following:

<p>${hello()}</p>

The result would be:

<p>&lt;hello>world&lt;hello></p>

Calling the XML function would have given us the result we intended:

<p>${XML(hello())}</p>

<p><hello>world</hello></p>

The xmlns keyword parameter can be used to set the default XML namespace for the top-level elements in the supplied content:

<p>${XML(hello(), xmlns="cid:hello_example")}</p>

<p><hello xmlns="cid:hello_example">world</hello></p>

This is especially useful when including XHTML content that lacks an XML namespace declaration.

6.2   document() function

The document function loads an XML document from a file or URL allowing it to be embedded in template output:

<div py:content="document('header.html')"></div>

The document function resolves paths relative to the current template file (if the template location is available).

6.3   defined(name) and value_of(name, default) functions

defined returns True if the name exists in the Kid namespace. value_of returns either the named value or the optional default value if that name doesn't exist in the namespace. These two simple convenience functions may be more intuitive to many than hasattr(self, name) and getattr(self, name, default) which are exactly equivalent.

7.1   Repetition/Iteration (py:for)

<element py:for="target_list in expression_list" />

Works exactly like the Python for statement.

The py:for attribute may appear on any element to signify that the element should be processed multiple times, once for each value in the sequence specified:

<?python
bottles = range(1, 101)
bottles.reverse()
?>
<p py:for="num in bottles">
   <span py:content="num">X</span> bottles of beer on the wall,
   <span py:content="num">X</span> bottles of beer on the wall,
   take one down, pass it around, <span py:content="num - 1">X - 1</span>
   bottles of beer on the wall.
</p>

The py:for attribute is the first attribute to be processed if present. All other py: attributes are processed for each iteration of the loop.

7.2   Conditionals (py:if)

<element py:if="expr" />

The py:if attribute may appear on any element to signify that the element and its decendant items should be output only if the boolean expression specified evaluates to true in Python:

<p py:if="5 * 5 == 25">
  Python seems to be handling multiplication okay.
</p>

The py:if attribute is processed after the py:for attribute and is evaluated for each iteration. If the result of evaluating expr as a boolean expression is false in Python, no further py: attributes are processed for the current iteration or, if not in a py:for, at all.

7.3   Dynamic Content (py:content)

<element py:content="expr" />

This attribute MAY appear on any element to signify that the decendant items of the element are to be replaced with the result of evaluating expr.

<p py:content="time.strftime('%C %c')">The Time</p>

... results in:

<p>Tues, Jun 26, 2004 02:03:53 AM</p>

py:content is a Content Producing Construct and can output both character and structured data.

If expr evaluates to None the element will be output as an empty element.

<p py:content="None">i go away</p>

... results in:

<p />

7.4   Replacing Content (py:replace)

<element py:replace='expr' />

py:replace is shorthand for specifying a py:content and a py:strip="True" on the same element:

<?python
x = 10
?>
<p><span py:replace="x">...</span></p>

... results in:

<p>10</p>

... and is equivelant to specifying:

<?python #
x = 10
?>
<p><span py:strip="" py:content="x">...</span></p>

The py:replace attribute is processed after the py:for and py:if attributes. py:strip and py:content attributes are not processed and are discarded.

py:replace is a Content Producing Construct and can output both character and structured data.

If expr evaluates to None the element will be output as an empty element.

<test><p py:replace="None"><span>i go away</span></p></test>

... results in:

<test />

7.5   Stripping Tags (py:strip)

<element py:strip="expr" />

The py:strip attribute may apppear on any element to signify that the containing element should not be output. If the attribute value is blank (no expr at all) or if the result expr is a boolean expression that evaluates to true, the element is not output, but all descendant elements are processed normally. If expr is not blank and the result of evaluating expr as a boolean expression is false, processing continues as if the attribute did not exist.

The py:strip attribute MAY appear on an element with any other kid attribute. However, if both a py:replace and a py:strip exist on the same element, the py:strip attribute is ignored and discarded.

The py:strip attribute is processed after the py:for and py:if attributes. If omission is eminent, the py:content attribute is processed normally but attribute interpolation does not occur.

7.6   Dynamic Attributes (py:attrs)

<element py:attrs="expr" />

The py:attrs attribute may appear on any element to specify a set of attributes that should be set on the element when it is processed. The expression specified MUST evaluate to one of the following types of values:

dict

A dictionary with keys specifying attribute names and values specifying attribute values. These are added to the attributes of the current element by calling element.attrib.update(mapping), where element is an ElementTree Element object and mapping is the dictionary returned from the expression. Outer curly braces are not necessary to write down.

list

A list of tuples of the form (name, value) is also acceptable. Each item of the list is added to the current set of attributes by iterating over the list and calling element.set(name, value).

keyword arguments

The attributes can also be specified as comma separated keyword arguments of the form name=value.

The following lines:

<elem py:attrs="{'a':1, 'ns:b':2}" />
<elem py:attrs="'a':1, 'ns:b':2" />
<elem py:attrs="(('a',1), ('ns:b',2))" />
<elem py:attrs="a=1, ns:b=2" />

will all produce the same output:

<elem a="1" ns:b="2" />

Note that attributes whose values are None will be removed. If a blank attribute is desired, an empty string should be used.

If the expression specified is an empty dictionary or an empty list, the attributes are not modified in any way.

py:attrs is a Content Producing Construct, but can output only character data.

7.7   Named Template Functions (py:def)

<element py:def="template_name(arg_list)" />

The py:def attribute may appear on any element to create a "Named Template Function". Markup contained within an py:def element is not output during normal template expansion but can be referenced from other Content Producing Constructs to insert the markup at the point referenced.

Like normal Python functions, Named Template Functions have an optional argument list that may use all of the jazzy features of Python argument lists like variable and keyword arguments.

Named Template Functions are invoked exactly like normal Python functions. They are generally invoked from Content Producing Constructs like py:content or ${} substitution.

Here we will define two Named Template Functions: display_list and display_dict. The first function takes a sequence and the second a mapping. We can invoke these functions from the same template by invoking them from a content producing construct:

<html xmlns:py="http://purl.org/kid/ns#">
   <body>
      <ul py:def="display_list(seq)">
         <li py:for="item in seq" py:content="item" />
      </ul>

      <table py:def="display_dict(mapping)">
         <tr>
            <th>Key</th>
            <th>Value</th>
         </tr>
         <tr py:for="key, value in mapping.items()">
            <td py:content="key" />
            <td py:content="value" />
         </tr>
      </table>

      ${display_list(['apple', 'orange', 'kiwi'])}

      <div py:replace="display_dict({'x' : 'y', 'p' : 'q'})">
         Key/Value Table replaces this text
      </div>
   </body>
</html>

Serialized as XML this becomes something like:

<?xml version="1.0" encoding="utf-8"?>
<html>
   <body>
      <ul>
         <li>apple</li><li>orange</li><li>kiwi</li>
      </ul>
      <table>
         <tr>
            <th>Key</th>
            <th>Value</th>
         </tr>
         <tr>
            <td>x</td>
            <td>y</td>
         </tr>
         <tr>
            <td>p</td>
            <td>q</td>
         </tr>
      </table>
   </body>
</html>

7.8   Match Templates (py:match)

<element py:match="expr" />

The py:match attribute may appear on any element to create a "Match Template". Markup contained within a Match Template element is not output during normal template expansion. Instead, these constructs set up filters for expansion output that are capable of transforming content as it is generated.

Match Templates are generally used to insert content dynamically based on patterns in template expansion or to provide "custom tag" functionality similar to that found in JSP taglibs or XSLT.

A Match Template has two parts: the match expression part (expr) and the body part (the element and it's descendants).

Match Templates are processed as follows:

1. Each element that is output from a template goes through the Match Template Filter.
2. The Match Template Filter visits each of the Match Templates defined in the current template and the templates the current template extends in the order that they are defined and evaluates the associated match expression.
3. If the match expression returns true as a boolean expression, the match template's body is expanded and replaces the original element and all of its descendants.

In both the match expression and in the match template's body, the item name is bound to the Element that is being output. However, there are some limitations to what can be accessed at each phase:

1. During match expression evaluation, only the item Element and none of its descendants are available. This means that match expressions are limited to testing matches based on the immediate Element's tag and attributes [1].
2. During match template expansion (that is, when the match expression is true), the element's descendants are available and may be referenced from Content Producing Constructs to output bits and pieces of the matched items structure.

When matching the item.tag you need to keep your namespaces in mind. A common problem is to use the expression item.tag == 'body' when the document has a default namespace declared. When the default namespace is declared the XML parser will rename the tags using clark notation. So the correct expression would be something like item.tag == '{http://www.w3.org/1999/xhtml}body'.

<?xml version="1.0" encoding="utf-8"?>
<?python
from time import localtime
def timeofday():
    """Get time of day ('am' or 'pm')"""
    return localtime().tm_hour < 12 and 'am' or 'pm'
?>
<html xmlns:py="http://purl.org/kid/ns#">
  <!-- define the greeting match template -->
  <span py:match="item.tag == 'greeting'"
        py:replace="item.get(timeofday())">
  </span>

  <head>
    <title>Time of day demo</title>
  </head>
  <body>
    <p>
      Good <greeting am="Morning!" pm="Afternoon" />
    </p>
  </body>
</html>

<html>
  <head>
    <title>Time of day demo</title>
  </head>
  <body>
    <p>
      Good Morning!
    </p>
  </body>
</html>

<?xml version="1.0" encoding="utf-8"?>
<?python
from time import localtime
def timeofday():
    """Get time of day ('am' or 'pm')"""
    return localtime().tm_hour < 12 and 'am' or 'pm'
?>
<html xmlns:py="http://purl.org/kid/ns#">
  <!-- define the greeting match template -->
  <span py:match="item.tag == 'greeting'"
        py:replace="item.get(timeofday())">
  </span>
</html>

<?xml version="1.0" encoding="utf-8"?>
<html py:extends="'common.kid'">
  <head>
    <title>Time of day demo</title>
  </head>
  <body>
    <p>
      Good <greeting am="Morning!" pm="Afternoon" />
    </p>
  </body>
</html>

7.9   Template Reuse (py:extends)

<root py:extends="template1, template2, ...">

The py:extends attribute may appear on the root element to specify that the template should inherit the Named Template Functions and Match Templates defined in another template (or set of templates). If a py:extends attribute is specified, it MUST be on the root element of the document.

The py:extends may contain a list of Python expressions separated by commas that reference templates. The rules for what types of values may be specified are:

string

The name of a template file, relative to the current template file.

Example:

<html py:extends="'common.kid'" />

module or Template class

The py:extends variable references a module or a Template class. If a module is referenced, an attempt is made to find a class named Template belonging to the that module.

Example:

<?python
import common
?>
<html py:extends="common" ...

Multiple templates may be referenced by separating each by a comma. The following example references templates common and forms, imported using the import hooks and a template filename named other.kid:

<?python
import common, forms
?>
<html py:extends="common, forms, 'other.kid'" ...

<html xmlns:py="http://purl.org/kid/ns#">

  <ul py:def="display_errors(errors)">
    <li py:for="error in errors" py:content="error" />
  </ul>

  <strong py:match="item.tag == 'b'"
    py:content="item.text.upper()" />

</html>

<html py:extends="'common.kid'"
      xmlns:py="http://purl.org/kid/ns#">
  <head>
    <title>Errors</title>
  </head>
  <body>
    <p>The following <b>errors</b> were found:</p>
    ${ display_errors(["Field is required", "Must be phone number.."]) }
  </body>
</html>

7.10   Layout Templates (py:layout)

<root py:layout="base_layout">

The py:layout attribute may appear on the root element to specify that a content template should use the referenced template as a layout template. This allows separation of individual page content from site-wide layout elements such as headers, menus, footers, etc. Match Templates, Named Template Functions, and layout parameters defined in a content template will be applied to the layout template. If a py:layout attribute is specified, it MUST be on the root element of the document.

The py:layout attribute may contain a single Python expression that references a layout template. The rules for what types of values may be specified are:

string

The name of a template file, relative to the current template file.

Example:

<html py:layout="'base_layout.kid'" />

module or Template class

The py:layout variable references a module or a Template class. If a module is referenced, an attempt is made to find a class named Template belonging to the that module.

Example:

<?python
import base_layout
?>
<html py:extends="base_layout" ...

<html xmlns:py="http://purl.org/kid/ns#">

  <head>
    <title>App Name - ${page_title}</title>

    <link href="layout.css" type="text/css" rel="stylesheet" />
    ${page_specific_css()}
  </head>

  <body>
    <h1>Now viewing: ${page_title} of App Name</h1>

    <content>Default content</content>

    <div class="footer">Page Footer Text</div>
  </body>

</html>

<?python
layout_params['page_title'] = "Content Page 1 of 10"
?>
<html py:layout="'base_layout.kid'"
      xmlns:py="http://purl.org/kid/ns#">

  <link py:def="page_specific_css()"
    href="layout.css" type="text/css" rel="stylesheet" />

  <div py:match="item.tag == 'content'">
    <ul>
      <li>Content Item 1</li>
      <li>Content Item 2</li>
      <li>Content Item 3</li>
    </ul>
  </div>

</html>