7. Classes

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:

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:

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