5. The template object model

About the object model

The HTMLTemplate object model is really just a greatly simplified, highly specialised variation of the standard DOM, in which only specified HTML elements can be manipulated via a very compact, simple API that's designed specifically for templating.

The template object model is constructed from three classes: Template, Container and Repeater (a subclass of Container).

Template objects

The Template object forms the template's root node, representing the complete HTML document. It contains one or more Container and/or Repeater child nodes, and implements the render method used to generate finished pages.

Container objects

A Container object represents a modifiable HTML element. e.g.:

<title node="con:pagetitle">...</title>

The HTML element may be empty - e.g. <br /> - in which case it has no content and only its tag attributes are modifiable, or non-empty - e.g. <p>...</p> - in which case it may contain either modifiable content (plain text/markup) or other Container and/or Repeater nodes.

The standard Container node has a one-to-one relationship with its parent node, appearing only once when rendered.

Note that if a Container object's omit method is called, the HTML element it represents is omitted from the finished page. If its omittags method is called, only its content is included in the finished page.

Repeater objects

A Repeater node is a Container node that has a one-to-many relationship with its parent node, appearing zero or more times - once for each item in the collection being iterated by its repeat method. e.g.:

<ul>
    <li node="rep:listitem">...</li>
</ul>

The Repeater class's repeat method operates in a similar fashion to Python's built-in map function, except that that it passes an extra argument to the supplied callback function and doesn't return a result. For example, the call:

repeaternode.repeat(callback, [1, 2, 3, 4, 5], *args)

will call the given callback function five times, each time passing it a copy of repeaternode along with an item from the given list, as well as any additional arguments supplied by the user. The callback function can then manipulate the supplied Repeater object, inserting data into the HTML element's tag attributes and/or content, or modifying its child nodes, or calling its omit method to prevent that instance of the Repeater from being rendered in the finished page.