Previous Chapter | Next Chapter | Up | Next Section | Contents

Displaying Information Hierarchically: the dtml-tree tag


Zope objects are organized and presented in a hierarchical fashion, so it is only natural that there should be a DTML facility to aid in the hierarchical display of information. This facility is the dtml-tree tag. The dtml-tree tag is similar to the dtml- in tag, in that it is applied to objects that contain other objects. However, in addition to iterating over sub-objects, the dtml-tree tag provides the ability to expand and iterate over sub-objects of sub-objects.

The dtml-tree tag provides many options which allow you quite a bit of control over how the tree is displayed.

Figure 11 shows two tree views of a Zope site with and without a folder expanded. This view is generated with the DTML shown in figure 12.

A tree view of a folders in a Zope "school" site with
(a) no top-level folders expanded and (b) the Grades folder expanded

 

 

(a)

(b)
DTML source to produce the tree views shown in figure 11.

<dtml-var standard_html_header>

<dtml-tree>
<dtml-var id>
</dtml-tree>

<dtml-var standard_html_footer>

This example shows an extremely simple form of the dtml-tree tag. No attributes are used. Although the dtml-tree tag can use the standard name and expr attributes to specify data to be displayed, these attributes may be and usually are omitted. The dtml-tree tag usually uses the current folder as the source of data to be displayed. The text following the dtml-tree tag is inserted for each "branch" of a tree. The attributes that can be used with the dtml-tree tag are summarized in table 21.

dtml-tree tag attributes.

Name

Value required?

Description

name

yes

Insert the name of the variable to be inserted.

expr

yes

Insert an expression that evaluates to the value to be inserted.

branches

yes

The name of the method used to find sub-objects. This defaults to tpValues, which is a method defined by a number of objects in Zope and in Zope products.

branches_expr

yes

An expression which is evaluated to find sub-objects. This attribute performs the same function as the branches attribute but uses an expression rather than the name of a method.

id

yes

The name of a method or attribute used to determine the id of an object for the purposes of calculating tree state. This defaults to tpId which is a method defined by many Zope objects. This attribute is mostly useful for developers who wish to have fine control of the internal representation of the tree state.

url

yes

The name of a method or attribute used to determine the url of an object. This defaults to tpURL which is a method defined by many Zope objects. This attribute is mostly useful for developers who wish to have fine control over tree url generation.

leaves

yes

The name of a Document used to expand sub-objects that do not have sub-object branches.

header

yes

The name of a Document to be shown at the top of each expansion. This provides an opportunity to "brand" a branch in a hierarchy. If the named document cannot be found for a branch, then the header attribute is ignored for that branch.

footer

yes

The name of a Document to be shown at the bottom of each expansion. If the named document cannot be found for a branch, then the footer attribute is ignored for that branch.

nowrap

yes

Either 0 or 1. If 0, then branch text will wrap to fit in available space, otherwise, text may be truncated. The default value is 0.

sort

yes

Sort branches before text insertion is performed. The attribute value is the name of the attribute that items should be sorted on.

assume_children

yes

Either 0 or 1. If 1, then all items are assume to have sub-items, and will therefore always have a plus sign in front of them when they are collapsed. Only when an item is expanded will sub-objects be looked for. This could be a good option when the retrieval of sub-objects is a costly process.

single

yes

Either 0 or 1. If 1, then only one branch of the tree can be expanded. Any expanded branches will collapse when a new branch is expanded.

skip_unauthorized

yes

Either 0 or 1. If 1, then no errors will be raised trying to display sub-objects to which the user does not have sufficient access.

By default, the dtml-tree tag displays branches and sub-branches of an object. Branches are normally found by calling a method named tpValues of the object being displayed by the dtml-tree tag. Many Zope objects, including folders, provide tpValues methods. Alternatively, the branches method may be used to specify a different method to call to find branches. For example, to display all sub-objects of a folder, the objectValues method may be used (figure 13).

Use of the branches tag to display all sub-objects in a folder.



<dtml-var standard_html_header>

<dtml-tree branches=objectValues>
<IMG SRC="<dtml-var SCRIPT_NAME
>/<dtml-var icon>">
<dtml-var id>
</dtml-tree>

<dtml-var standard_html_footer>

 

An object that does not have sub-branches may instead define "leaves" by using the leaves attribute of the dtml-tree tag. The argument to the leaves attribute is a Document object. This is commonly used when browsing database data. Branches are used to provide a hierarchical organization to data and leaves are used to display data within a hierarchical grouping.

The header and footer attributes are similar to the leaves attribute, in that they are used to specify documents to be displayed when a branch is expanded. Unlike the leaves attribute, they are only used when there are sub-branches of an object. The header document is displayed before the display of sub-branches, and the footer is displayed following sub-branches.

The dtml-tree tag sets a number of variables in the DTML namespace as it renders sub-objects. These variables allow sub-objects to tailor their representation to their position within the tree. Perhaps the most useful variable set by the dtml-tree tag is the tree-item-expanded variable. If this variable is true then the tree item knows that it has been expanded. The variables set by the tree tag are summarized in Table 26.

Variables set by the dtml-tree tag when rendering sub-objects.

Name

Description

tree-item-expanded

True is the current item is expanded.

tree-item-url

The URL of the current item relative to the URL of the DTML document in which the tree tag appears. This variable relies on the tree tag's url attribute to generate the tree-item URL

tree-root-url

The URL of the DTML document in which the tree tag appears.

tree-level

The depth of the current item. Items at the top of the tree have a level of 0.

tree-colspan

The number of levels deep the tree is being rendered. This variable along with the tree-level variable can be used to calculate table rows and colspan settings when inserting table rows into the tree table.

tree-state

The tree state expressed as a list of ids and sub-lists of ids. This variable is mostly of interest to developers who which to have precise knowledge of a tree's state.

Additionally, the dtml-tree tag responds to several variables set the DTML namespace. You can expand and collapse the entire tree by setting the expand_all and collapse_all variables. Table 27 details the variables which control tree state.

Variable that influence the dtml-tree tag

Name

Description

expand_all

If set to a true value, this variable causes the entire tree to be expanded.

collapse_all

If set to a true value, this variable causes the entire tree to be collapsed.

tree-s

This variable contains the tree state in a compressed and encoded form. This variable is set in a cookie to allow the tree to maintain its state. Developers may control the state of the tree directly by setting this variable, though this is not recommended.

tree-e

This variable contains a compressed and encoded list of ids to expand. Developers may control the state of the tree directly by setting this variable, though this is not recommended.

tree-c

This variable contains a compressed and encoded list of ids to collapse. Developers may control the state of the tree directly by setting this variable, though this is not recommended.

One common application of these variables is to provide links which allow a tree to be expanded and collapsed. Here's an example of how this could be done in DTML:

<P>

<a href="<dtml-var URL0>?expand_all=1">Expand tree</a> |

<a href="<dtml-var URL0>?collapse_all=1">Collapse tree</a>

</P>

This snippet of DTML provides two links to the current page. One link will cause the current page's tree to expand, the other will cause it to collapse.

 

Previous Chapter | Next Chapter | Up | Next Section | Contents