4. Template design

About HTML templates

An HTML template is usually a complete HTML/XHTML document, though it may also be a fragment of one - HTMLTemplate doesn't require the document be complete, nor even that it has a single root element.

To create a Template object model, selected HTML elements must be annotated with 'compiler directives', special tag attributes that indicate how the object model is to be constructed. Here are some examples:

<h1 node="con:title">Welcome</h1>

<img node="con:photo" src="" />

<a node="rep:navlink" href="#">Catalogue</a>

<span node="-sep:navlink"> | </span>

<div node="del:"> ... </div>

One restriction does apply when authoring templates: the template's HTML elements must be correctly closed according to XHTML rules. For example, this markup is acceptable:

<p>Hello World</p>

<hr />

but this is not:

<p>Hello World

<hr>

Compiler directives

HTMLTemplate defines four types of compiler directive:

The special attribute name can be anything (the default is node but any other name may be specified via the Template constructor), and its values are typically of form FOO:BAR, where FOO is a three-letter code indicating the type of directive and BAR is the name of the node to create.

Every node name must be a valid Python identifier with two additional restrictions:

  1. A node name cannot begin with an underscore.
  2. A node name cannot match the name of any method or property belonging to the Container, Repeater and Template classes.

Note that the del directive doesn't create a named node, so may simply be written as del:. Directive types and node names are both case-sensitive.

HTMLTemplate also supports a single directive modifier, -, also known as the 'minus tags' modifier. When prepended to a directive, e.g. -con:foo, the minus tags modifier indicates that the HTML element's tags should be omitted in the compiled node/separator string. Use this modifier when adding an arbitrary HTML element (typically <div> or <span>) to an HTML template purely to construct a node or separator string to prevent the rendered page being cluttered with the leftover tags.