API Reference

This document explores the API of this package.


Static tree interfaces

interface zope.app.tree.interfaces.IUniqueId[source]

Interface that promises to return a unique id within a tree.

Problem: How are implementing objects (most probably adapters) supposed to know, whether their id is unique in the context? Well, they just have to be damn sure that they are unique.


Return a string containing a unique id within a tree

interface zope.app.tree.interfaces.IChildObjects[source]

Interface providing methods to retrieve child objects so they can be wrapped in tree nodes.


Return true if child objects are available


Return a sequence of child objects

interface zope.app.tree.interfaces.INode[source]

Extends: zope.app.tree.interfaces.IUniqueId, zope.app.tree.interfaces.IChildObjects

A node in the tree


The object that is being wrapped.



The positional depth of this node in the tree.



True if this node is expanded.


Expand this node.

‘recursive’ can be set to True to expand all child nodes as well


Collapse this node.


Return a sequence of children nodes if the node is expanded.


Return a flat list of nodes in the tree. Children of expanded nodes are shown.


Return information of all nodes in a flat tuple and the maximum depth.

The tuple consists of node information dictionaries. Each directionary has the following keys:

  • ‘node’: This is the node itself.

  • ‘tree-state’: A hash value that uniquely identifies the expansion state of the node.

  • ‘row-state’: When representing the node in a GUI it is necessary to know whether the levels higher up are opened or not. We use this information to decide whether we should or should not draw a vertical line in the tree.

    The ‘row-state’ value is simply a list of ‘True’ and ‘False’. ‘True’ signifies that a level is open and more elements of this level are expected further down.

  • ‘last-level-node’: A boolean that signifies whether a node is the last node of its level.

This method is intended for output formats that cannot handle nested values easily. An example here are Page Templates.

interface zope.app.tree.interfaces.ITreeStateEncoder[source]

This utility can encode and decode the ids of expanded nodes


Encode the tree expansion information in ‘expanded_nodes’.


Decode the tree expansion information ‘tree_state’.


A node in the tree

class zope.app.tree.node.Node(context, expanded_nodes=(), filter=None)[source]

Bases: object

A tree node

This object represents a node in the tree. It wraps the actual object and provides the INode interface to be relied on. In that way, it works similar to an adapter.

This implementation is designed to be as lazy as possible. Especially, it will only create child nodes when necessary.


See zope.app.tree.interfaces.INode


See zope.app.tree.interfaces.INode


See zope.app.tree.interfaces.INode


See zope.app.tree.interfaces.INode


See zope.app.tree.interfaces.INode


See zope.app.tree.interfaces.INode


See zope.app.tree.interfaces.INode

getFlatDicts(maxdepth=0, row_state=None)[source]

See zope.app.tree.interfaces.INode


Static tree utilities

class zope.app.tree.utils.TreeStateEncoder[source]

Bases: object

Encodes tree state.

Implements zope.app.tree.interfaces.ITreeStateEncoder.

>>> expanded_nodes = ['a', 'c', 'foobar']
>>> encoder = TreeStateEncoder()
>>> encoded = encoder.encodeTreeState(expanded_nodes)
>>> decoded = encoder.decodeTreeState(encoded)
>>> decoded == expanded_nodes

Encode a value as a cookie- and url-safe string.

Encoded string use only alphanumeric characters, and ”._-”.


Decode a b2a-encoded string.


Object adapters

This module contains adapters necessary to use common objects with statictree. The most prominent ones are those for zope.location.interfaces.ILocation and zope.container.interfaces.IReadContainer. We also provide adapters for any object, so we don’t end up with ComponentLookupErrors whenever encounter unknown objects.

class zope.app.tree.adapters.StubUniqueId(context)[source]

Bases: object

Implements IUniqueId for any object.

class zope.app.tree.adapters.StubChildObjects(context)[source]

Bases: object

Implements IChildObjects for any object.

class zope.app.tree.adapters.LocationUniqueId(context)[source]

Bases: object

Implements IUniqueId for locations.

class zope.app.tree.adapters.ContainerChildObjects(context)[source]

Bases: object

Implements IChildObjects for readable containers.

class zope.app.tree.adapters.ContainerSiteChildObjects(context)[source]

Bases: zope.app.tree.adapters.ContainerChildObjects

Adapter for read containers which are zope.component.interfaces.ISite as well.

The site manager will be treated as just another child object.



Child objects can be filtered out by certain criteria which are defined by a filter. Writing your own filter should be very easy. All you have to implement is the zope.container.interfaces.IObjectFindFilter interface. Already existing filters for the find machinery may be used with statictree just as well.

Since commonly needed, this module provides two filters that filter by interface.

class zope.app.tree.filters.OnlyInterfacesFilter(*filterby)[source]

Bases: object

Only match objects that implement one of the given interfaces.

class zope.app.tree.filters.AllButInterfacesFilter(*filterby)[source]

Bases: zope.app.tree.filters.OnlyInterfacesFilter

Match only objects that do not implement one of the given interfaces.

Browser Views

Browser views

interface zope.app.tree.browser.IStaticTreeLayer[source]

Extends: zope.publisher.interfaces.browser.IBrowserRequest

Layer that we can register our own navigation macro for.

class zope.app.tree.browser.StatefulTreeView(context, request)[source]

Bases: zope.publisher.browser.BrowserView

Basic stateful tree.

statefulTree(root=None, filter=None, tree_state=None)[source]

Build a tree with tree state information from a request.

Cookie Views

Stateful cookie tree

class zope.app.tree.browser.cookie.CookieTreeView(context, request)[source]

Bases: zope.app.tree.browser.StatefulTreeView

A stateful tree view using cookies to remember the tree state

cookieTree(root=None, filter=None)[source]

Build a tree with tree state information from a request.


Cookie tree with only folders (and site managers).


Cookie tree with only folders and the nearest site as root node.


Cookie tree with only folders and the root container as root node.


Cookie tree with only folders and the root container as root node.