9. Design tips

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:

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.