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 therepeat
method.**kwargs
: anything -- zero or more additional keyword parameters corresponding to any extra arguments passed by the template controller to therepeat
method.
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 therender
method.
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