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 tree tag. The tree tag is similar to the in tag, in that it is applied to objects that contain other objects. However, in addition to iterating over sub-objects, the tree tag provides the ability to expand and iterate over sub-objects of sub-objects.
The tree tag provides many options which allow you quite a bit of control over how the tree is displayed.
Figure See A tree view of a folders in a Zope "school" site with (a) no top-level folders expanded and (b) the Grades folder expanded shows two tree views of a Zope site with and without a folder expanded. This view is generated with the DTML shown in figure See DTML source to produce the tree views shown in figure 11..
![]() |
![]() |
<!--#var standard_html_header--> |
This example shows an extremely simple form of the tree tag. No attributes are used. Although the 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 tree tag usually uses the current folder as the source of data to be displayed. The text following the tree tag is inserted for each "branch" of a tree. The attributes that can be used with the tree tag are summarized in table 21.
Insert the name of the variable to be inserted. See The name attribute |
||
Insert an expression that evaluates to the value to be inserted. See The expr attribute |
||
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. |
||
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. |
||
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. |
||
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. |
||
The name of a Document used to expand sub-objects that do not have sub-object branches. |
||
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. |
||
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. |
||
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 branches before text insertion is performed. The attribute value is the name of the attribute that items should be sorted on. |
||
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. |
||
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. |
||
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 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 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 See Use of the branches tag to display all sub-objects in a folder.).
An object that does not have sub-branches may instead define "leaves" by using the leaves attribute of the 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 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 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 25.
Additionally, the 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 26 details the variables which control tree state.
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:
<a href="<!--#var URL0-->?expand_all=1">Expand tree</a> |
<a href="<!--#var URL0-->?collapse_all=1">Collapse tree</a>
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