[Zope] Tree Tag Options

[Martijn Pieters]

At Tue, 02 Feb 1999 13:01:32 -0800 Amos Latteier wrote a nice explanation
of the branches attribute of the tree tag.

But when I played around with the source of the tree tag (TreeTag.py), I
discovered more toys. This is has become an unofficial documentation of the
#tree tag. Excuse the typos, for it has become very late. Have fun.


Attributes of #tree

assume_children=[0|1] default 0
	If set to a nonzero value, all items are assumed to have subitems, and
will therefore allways have a + sign in front of them when not yet
expanded. Only when a user expands an item it is checked for subitems. This
could be a good option when the retrieval of children is a slow process.

branches="methodname" default="tpValues"
	If an object has defined this method, it should return a list of ids that
are it's subobjects. The default, tpValues, is defined on the Items class
(from which just about every objetc inherits), and Folders and Database
Adapters define their own versions. If you use objectValues as method, you
get the same effect on Folders, but not on Database Adapters.

branches_expr="expression"
	branches_expr works like the expr attribute of tags like #if. You could
therefore do:
<!--#tree branches_expr="objectValues(['Folder', 'DTML Document'])"--> 
to get a tree of only Folder and Document subobjects. This is easier than
defining your own External Method for branches="", like Amos described.

id="method_or_propertyname" default="tpId"
	Method or property name to determine the ID of the object for tree-state
purposes. The Ids saved in the tree state cookie (and the tree-state local
var) are realy just integers so the state var is not too big, but unusable
for your average Zope developer. If you want to do anything with the state,
you might want to define this as id="id", for a more readable form.  Just do 
<!--#tree id="id"--><!--#var tree-state--><!--#/tree--> and see for
yourself. No default Zope object currently defines a tpId method or
property. When no tpId method or property is defined, an internally
generated integer is used (pickle id?).

leaves="property"
	If set, this property is assumed to be a DTML Method within objects that
have no sub-objects. It is displayed as part of the tree, no additional
code is needed in your DTML. The leave DTML method is handed a special
standard_html_header and standard_html_footer.

nowrap=[0|1] default 0
	If set to a nonzero value, the tree table will be rendered with the NOWRAP
attribute, which means the browser won't wrap the item labels when
spacially challenged.

url="method_or_propertyname" default="tpURL"
	Method or property to be called on object to determine the relative URL of
the object. The default, tpURL, is defined by the Item class, and the
Gladfly Database Adapter defines it's own version, so it can show you it's
tables and columns in the management screen. If you want to override the
URL translation, define an External Method, like Amos described, and use
that method with url="methodname".

single=[0|1] default 0
	If set to a nonzero value, only one branch on a level can be expanded. Any
other expanded branches will collapse. Seriously cool.

skip_unauthorized=[0|1] default 0
	If set to a nonzero value, no ValidationErrors will be raised trying to
read objects to which the user has no access.



Variables in namespace set by tree tag (for every object being rendered):

tree-root-url
	Relative URL of the DTML Document or Method this tag is in.

tree-colspan
	The number of levels deep the tree is being rendered.

tree-state
	The current state of the tree, a list of ids and sublists.

tree-item-url
	The URL of the current object being rendered, relative to the document the
#tree tag is in. This is generated using the url="methodname" method.

tree-level
	Level of this object in the tree, starting at 0.

tree-item-expanded
	Flag indicating wether this item is expanded or not.



Variables in namespace that influence the tree tag:

expand-all
	All branches expanded if this name is defined and nonzero (like in a
cookie, or in the REQUEST object. Try
http://URL/to/object/with/tree/tag?expand-all=1).

collapse-all
	All branches collapsed if present and nonzero.	

tree-s
	This is the cookie and query name that contains the state of the tree.
This is a zlib compressed, base64 encoded nested list of ID's. Have fun
making one yourself. I think you better start with the TreeTag.py code.

tree-e
	List of ID's to expand. See tree-s on the format.

tree-c
	List of ID's to collapse. Again, see tree-s.



Are we going to collect this kind of data somewhere? Like in a tag reference? 
Is there a protocol to define your own DTML tags?