Template design tips
Where two or more sibling nodes share the same type and name, only the first is included in the compiled template and the rest discarded. (If two or more sibling nodes share the same name but have different types, then unless the first node is type rep
and the other of type sep
a ParseError
will occur.)
The parser automatically removes the special attribute from any element it converts into a template node. Tag attributes whose name is the same as that used for special attributes but whose value isn't a recognised compiler directive are treated are left unchanged.
Separators must be declared after their corresponding Repeater
nodes.
When authoring a template, you'll sometimes want to group two or more adjacent nodes so they can be repeated as a single block. If the HTML doesn't already contain a suitable parent element to add the rep
compiler directive to, insert an extra <div>
or <span>
element that wraps these nodes and add the rep
directive to convert it to create your Repeater
node. You can the use the 'minus tags' modifier to omit this element from the rendered page. Tutorial 2 covers this technique in more detail.
Controller design tips
When setting a node's content, make sure you write:
node.foo.content = val
not:
node.foo = val
The first assigns val
as the node's content, the second replaces the node itself.
Template rendering tips
The attributes property, atts, performs basic validation of user-supplied attribute names and values for security:
- An attribute's name must match the pattern
^[a-zA-Z_][-.:a-zA-Z_0-9]*$
- An attribute's value may not contain both single and double quotes.
While HTMLTemplate will single/double-quote attribute values as appropriate, it won't perform any special encoding of values. Any attribute value encoding is left to the user's code, e.g. using urllib's quote
and unquote
functions.
Miscellaneous notes
The public class structure shown in this documentation is slightly simplified from the actual (multiple inheritance-based) implementation to make it easier to understand. This is not something end users should worry about.