Node
This abstract base class is subclassed by the Template, Container and Repeater classes from which the template object model is constructed. Each node in the object model contains zero or more named properties corresponding to the node definitions in the original HTML template.
Node
Properties:
NAME : Container | Repeater -- a (child) node defined by
the source HTML template (NAME = the node's name).
A template object may contain any number of these
properties.
Attributes
Each Container and Repeater object contains an Attributes instance representing the HTML element's attributes This is a simple dict-like structure that supports getting, setting and deleting attributes by name.
Attributes
Methods:
__getattr__(self, name) -- get an attribute
name : string -- the attribute's name
Result : string -- the attribute's value
__setattr__(self, name, value) -- set an attribute
name : string -- the attribute's name
value : string -- the attribute's value
__delattr__(self, name) -- delete an attribute
name : string -- the attribute's name
For example, to set the href attribute of an <a> tag:
node.atts['href'] = 'foo.html'
Container
Container objects represent HTML elements whose content can be manipulated by controller code. A Container node is rendered once, unless its omit method is called, in which case it won't appear at all. The original HTML template defines a Container node using the con directive (e.g. node="con:title").
Container(Node)
Properties:
atts : Attributes -- the tag's attributes
content : string -- the HTML element's content with &<>"
characters automatically escaped (note: when
inserting raw HTML, use the raw property instead)
raw : string -- the HTML element's raw content
(i.e. no automatic character escaping)
Methods:
omit(self) -- don't render this node
omittags(self) -- don't render this node's tags, only its
content
Note: if the Container object is derived from an empty HTML element (e.g. <br />), setting its content or raw property has no effect.
Repeater
Repeater objects are containers that can appear any number of times in the rendered output. The original HTML template defines a Repeater node using the rep directive (e.g. node="rep:list_item").
Repeater(Container) -- A mutable, repeatable HTML element ('rep')
Methods:
repeat(self, callback, sequence, *args, **kwargs) -- render an
instance of this node for each item in sequence
callback : function -- the function to call for each
item in the sequence
sequence : list -- a list, tuple, or other iterable
collection
*args : anything -- any values to be passed directly
to this node's callback function
**kwargs : anything -- any values to be passed directly
to this node's callback function
The repeat method's callback argument must be a function that accepts the following arguments:
node: instance -- a copy of the Repeater objectitem: anything -- an item from the sequence being iterated*args: anything -- zero or more additional parameters corresponding to any extra arguments passed by the template controller to therepeatmethod.**kwargs: anything -- zero or more additional keyword parameters corresponding to any extra arguments passed by the template controller to therepeatmethod.
Template
The top-level node in the template object model is represented by a Template object. This represents the complete HTML template and may contain any number of Container and/or Repeater sub-nodes. The Template class's constructor takes a minimum of two arguments: a string representing the HTML template to be parsed, and a callback function containing the top-level controller code responsible for rendering the Template object when its render method is called.
Template(Node) -- The top-level template node
Methods:
__init__(self, callback, html, attribute='node',
codecs=(defaultEncoder, defaultDecoder),
warnings=False)
callback : function -- the main function controlling
template rendering
html : string or unicode -- the HTML template
[attribute : string or unicode] -- name of the tag
attribute used to hold compiler directives
[codecs : tuple] -- a tuple containing two functions
used by attribute values and the content
property to encode/decode HTML entities
[warnings : boolean] -- warn when non-directive
attribute is encountered
render(self, *args) -- render this template
*args : anything -- any values to be passed directly
to this template's callback function
structure(self) -- print the object model's structure
for diagnostic use
The __init__ method's callback argument must be a function that accepts the following arguments:
node: instance -- a copy of the Template object*args: anything -- zero or more additional parameters corresponding to any extra arguments passed by the template controller to therendermethod.
HTMLTemplate's default codecs encode/decode the following markup characters: &<>". When supplying your own codecs functions via the __init__ method's codecs argument, each function should accept and return a single string/unicode value. The first function should convert specified characters into HTML entities; the second should perform the reverse operation.
ParseError
In the event that the Template class's constructor is unable to parse the supplied HTML template string (e.g. due to badly formed HTML), a ParseError exception will be raised.
ParseError(Exception) -- A template parsing error