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:
con
defines a Container node that can appear only once at the given locationrep
defines a Repeater node that can appear any number of timessep
defines a separator string to be inserted between each iteration of a Repeater object of the same namedel
indicates a section of markup to be omitted in the compiled template.
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:
- A node name cannot begin with an underscore.
- A node name cannot match the name of any method or property belonging to the
Container
,Repeater
andTemplate
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.