What is zope.app.tree?

This package was designed to be a light-weight and easy-to-use static tree implementation. It allows the developer to quickly create trees with nodes that can be opened and closed without the use of JavaScript. The tree state can be retained over multiple sessions.

Documentation is hosted at https://zopeapptree.readthedocs.io

Overview

What is zope.app.tree?

ZopeTree is a port of Philipp’s Zope2 product ZopeTree. ZopeTree was meant to be a light-weight and easy-to-use static tree implementation, mainly designed for use in ZPTs. It was originally written because Zope2’s ZTUtils.Tree was found to be too complicated and inflexible.

The ZTUtils package has not been ported to Zope3. Parts of it, like batching, have found their way into Zope3, though. Only support for static tree generation is not in the core.

How to use it

Using the skin

ZopeTree comes with a pre-defined skin, StaticTree. It looks just like Zope3’s default skin, zope.app.rotterdam.Rotterdam, except that it displays a static tree in the navigation box instead of the Javascript/XML based dynamic tree.

Using predefined views on objects

ZopeTree comes with several predefined views:

cookie_tree

simple view using cookies for tree state storage.

folder_cookie_tree

same as above, however only showing folders.

site_cookie_tree

same as above, with the nearest site as root node.

root_cookie_tree

same as above, with the traversal root container as root node.

virtualhost_cookie_tree

same as above, but using the request’s virtual host root instead of the traversal root.

The example page template(s) in the browser package give an idea how to use these views for HTML templating.

Customization

The best way to customize ZopeTree is to define your own view for objects (usually ‘*’). If you want to use the cookie functionality, simply extend the cookie browser view:

>>> from zope.app.tree.filters import OnlyInterfacesFilter
>>> from zope.app.tree.browser.cookie import CookieTreeView

>>> class BendableStaticTreeView(CookieTreeView):
...
...  def bendablesTree(self):
...        # tree with only IBendables, but also show the folder
...        # they're in
...        filter = OnlyInterfacesFilter(IBendable, IFolder)
...        return self.cookieTree(filter)

You can also write your own filters. All you have to do is implement the IObjectFindFilter interface (which is trivial):

>>> from zope.interface import implementer
>>> from zope.container.interfaces import IObjectFindFilter

>>> @implementer(IObjectFindFilter)
... class BendableFilter(object):
...
...    def matches(self, obj):
...        # only allow bendable objects
...        return obj.isBendable()

License and Copyright

This product is released under the terms of the Zope Public License (ZPL) v2.1.

Copyright (c) 2003 Philipp “philiKON” von Weitershausen Copyright (c) 2004 Zope Corporation and Contributors

Credits

Thanks to ZopeMag (http://zopemag.com) for sponsoring development of the original ZopeTree product.

Thanks to Runyaga LLC (http://runyaga.com) for sponsoring the Zope3 port.

API Reference

This document explores the API of this package.

Interfaces

Static tree interfaces

interface zope.app.tree.interfaces.IUniqueId

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.

getId()

Return a string containing a unique id within a tree

interface zope.app.tree.interfaces.IChildObjects

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

hasChildren()

Return true if child objects are available

getChildObjects()

Return a sequence of child objects

interface zope.app.tree.interfaces.INode

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

A node in the tree

context

The object that is being wrapped.

depth

Depth

The positional depth of this node in the tree.

Implementation:zope.schema.Int Read Only:False Required:True Default Value:None Allowed Type:int, long

expanded

Expanded

True if this node is expanded.

Implementation:zope.schema.Bool Read Only:False Required:False Default Value:None Allowed Type:bool

expand(recursive=False)

Expand this node.

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

collapse()

Collapse this node.

getChildNodes()

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

getFlatNodes()

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

getFlatDicts()

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

This utility can encode and decode the ids of expanded nodes

encodeTreeState(expanded_nodes)

Encode the tree expansion information in ‘expanded_nodes’.

decodeTreeState(tree_state)

Decode the tree expansion information ‘tree_state’.

Nodes

A node in the tree

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

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.

expand(recursive=False)

See zope.app.tree.interfaces.INode

collapse()

See zope.app.tree.interfaces.INode

getId()

See zope.app.tree.interfaces.INode

hasChildren()

See zope.app.tree.interfaces.INode

getChildObjects()

See zope.app.tree.interfaces.INode

getChildNodes()

See zope.app.tree.interfaces.INode

getFlatNodes()

See zope.app.tree.interfaces.INode

getFlatDicts(maxdepth=0, row_state=None)

See zope.app.tree.interfaces.INode

Encoders

Static tree utilities

class zope.app.tree.utils.TreeStateEncoder

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
True

zope.app.tree.utils.b2a(s)

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

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

zope.app.tree.utils.a2b(s)

Decode a b2a-encoded string.

Adapters

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)

Bases: object

Implements IUniqueId for any object.

class zope.app.tree.adapters.StubChildObjects(context)

Bases: object

Implements IChildObjects for any object.

class zope.app.tree.adapters.LocationUniqueId(context)

Bases: object

Implements IUniqueId for locations.

class zope.app.tree.adapters.ContainerChildObjects(context)

Bases: object

Implements IChildObjects for readable containers.

class zope.app.tree.adapters.ContainerSiteChildObjects(context)

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.

Filters

Filters

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)

Bases: object

Only match objects that implement one of the given interfaces.

class zope.app.tree.filters.AllButInterfacesFilter(*filterby)

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

Extends: zope.publisher.interfaces.browser.IBrowserRequest

Layer that we can register our own navigation macro for.

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

Bases: zope.publisher.browser.BrowserView

Basic stateful tree.

statefulTree(root=None, filter=None, tree_state=None)

Build a tree with tree state information from a request.

Cookie Views

Stateful cookie tree

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

Bases: zope.app.tree.browser.StatefulTreeView

A stateful tree view using cookies to remember the tree state

cookieTree(root=None, filter=None)

Build a tree with tree state information from a request.

folderTree(root=None)

Cookie tree with only folders (and site managers).

siteTree()

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

rootTree()

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

virtualHostTree()

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

CHANGES

4.1.1 (unreleased)

• Nothing changed yet.

4.1.0 (2021-03-22)

• Add support for Python 3.7, 3.8 and 3.9.
• Add support for zope.component >= 5.
• Drop support for Python 3.4.
• Update PyPy versions.

4.0.0 (2017-05-16)

• Add support for Python 3.4, 3.5, 3.6 and PyPy.
• Fix #264614: Test for node filter didn’t do what it was expected to do.
• Import ISite from zope.component after it was moved there from zope.location.

3.6.0 (2009-02-01)

• Converted from using zope.app.container to zope.container.

3.5.1 (2009-01-29)

• Add compatibility for newer zope.traversing releases that require us to explicitly set up testing. This also works with older releases.

3.5.0 (2009-01-17)

• Get rid of zope.app.zapi dependency, replacing its uses with direct imports.
• Clean up dependencies, move testing and rotterdam dependencies to extra requires.
• Fix mailing list address to zope-dev@zope.org instead of retired zope3-dev@zope.org. Change cheeseshop to pypi in the package url.
• Replace __used_for__ in adapters.py with zope.component.adapts calls to make more sense.
• Remove obsolete zpkg files, zcml include file for mkzopeinstance-based installations, versions.txt that makes no sense now.

3.4.0 (2007-10-28)

• Initial release independent of the main Zope tree.

v1.2 (2004-02-19) – ‘Scruffy’

• Moved to zope.app.tree
• It is now called ‘ZopeTree’ again. Hoorray!
• Refactored browser stuff into its own browser subpackage.
• Separated the handling of tree state from the cookie functionality to provide a base class for views based on other tree state sources.

v1.1 (2004-02-16) – ‘Zapp’

• Added support for displaying lines in a tree (Stephan Richter)
  • Changes in Node.getFlatDict() to provide more data. Removed ‘depth’ from node info, but added ‘row-state’ and ‘last-level-node’. Changed interface and test accordingly.
  • Updated templates for StaticTree skin and example. Note that third party templates from 1.0.x will not work anymore and must be updated as well!

v1.0.1 (2004-01-16) – ‘Nibbler’

• Added last remaining pieces for unit tests
• Updated documentation
• Rounded some rough edges in the skin
• Integrated it into the Zope3 distribution below the zope.products package

v1.0 (2003-11-24) – ‘Lur’

• Ported to Zope 3
• Renamed it to ‘statictree’
• Much more unit tests
• Added filter functionality
• Provided sample implementations as well as an alternate rotterdam-like skin using the static tree

Development

zope.app.tree is hosted at GitHub:

https://github.com/zopefoundation/zope.app.tree/

Project URLs

• https://pypi.python.org/pypi/zope.app.tree (PyPI entry and downloads)

Indices and tables

• Index
• Module Index
• Search Page