TreeNavigator - Navigation in a tree structure
<head> <script src="prototype.js"></script> <script src="Keymap.js"></script> <script src="Navigator.js"></script> <link href="Navigator.css" rel="stylesheet" type="text/css"> </head> <body onload="new GvaScript.TreeNavigator('TN_tree')"> <div id="TN_tree"> <div class="TN_node"> <span class="TN_label">Label 1</span> <div class="TN_content"> <div class="TN_node"> <span class="TN_label">Label 1.1</span> <div class="TN_content"> ...Content of node 1.1 </div> </div> <div class="TN_leaf"> <span class="TN_label">Label 1.2 for leaf</span> </div> </div> </div> </div> </body>
Handles navigation in a data tree. The tree description is usual HTML, with some special classes to identify nodes. Nodes can be browsed, closed or opened. All operations take place directly within the tree, not in a separate panel.
To read further chapters of this documentation, use
the arrow keys or the TAB
key. To see the whole page at once (for example for
printing), press the Ctrl-keypad *
key.
A tree is a collection of nodes. Each node must have a label element and can have a content element. A node may be either open (its content is visible) or closed (its content is invisible). The label of the node is always visible, if the node itself is visible. Some nodes can be declared as leaves : in that case they have no content and have no open/close operations.
The content of a node may include other nodes, so a whole subtree may become invisible if the parent node is closed. Opening or closing nodes may be controlled by the mouse, by the keyboard, or through the programming interface.
A node's content may also by dynamic, by
specifying TN:contentURL
with the URL as value:
<div class="TN_node TN_closed" TN:contentURL="/my/url.html"> <div class="TN_label">Label for dynamic node</div> </div>
If the user opens that node, the content of the URL will by
dynamically fetched and inserted into the tree. The content then
stays there, but can be forcibly reloaded by hitting the
Ctrl-R
key.
The tree can be any HTML block element. It should contain one or
several block elements declared with class TN_node
or class
TN_leaf
-- usually these are DIV elements. Other HTML elements
may be freely interspersed with nodes, although this usually does not
make much sense for navigability.
Every node must in turn contain an inline element
declared with class TN_label
-- usually this is
a SPAN element. If the node is not a leaf, it may
then contain a block element declared
with class TN_content
-- usually this is
another DIV element. Both the label and the content
should be direct children of the node element.
At initialisation time, a new SPAN element is automatically inserted before each label, in order to add the +/- navigation buttons.
By default, the navigation buttons inserted on the
left of labels are small icons representing +/- signs.
To show other icons, change the CSS rules about the
TN_button
class:
.TN_button { background-image: url(myIconForOpenNodes.gif); } .TN_closed .TN_button { background-image: url(myIconForClosedNodes.gif); }
In addition, if you want another icon for illustrating the node's content (like for example an open or closed folder), you can proceed as follows:
add an empty span
element within the
labels that should have the icon
<span class="TN_label"><span class="specialNode"></span>some label</span>
define CSS background images for selectors
.specialNode
and .TN_closed .specialNode
,
as in the example above
All methods below take a node element as argument, i.e. are called according to pattern:
treeNavigator.method(node);
open(node)
opens the node
close(node)
closes the node
openAtLevel(elem, level)
walks down the tree and opens all subnodes of elem
until level
level
; closes nodes underneath
openEnclosingNodes(elem)
walks up the DOM, starting at elem
(which might by any element on
the page), and opens all nodes found on the way
select(node)
If there was a selected node, unselect it; then select the argument
node. The argument can be null
, in which case the tree no longer
has any selected node.
flash(node, duration, color)
Changes the background color of node to color for duration
milliseconds. Duration and color are optional and default to 200 ms
and 'red' (unless otherwise specified in the options to the
treeNavigator
constructor).
isClosed(node)
Returns true if the node is closed
isVisible(node)
Returns true if the node is visible
(i.e. does not have display:none
).
nextSibling(node)
Returns the next sibling tree node (i.e. next HTML sibling element
having class TN_node
; this is not equivalent to
node.nextSibling
).
previousSibling(node)
Returns the previous sibling tree node.
parentNode(node)
Returns the parent tree node.
firstSubNode(node)
Returns the first subnode within that node's content. If no argument is given, returns the first node of the tree.
lastSubNode(node)
Returns the last subnode within that node's content. If no argument is given, returns the last node of the tree.
lastVisibleSubNode(node)
Returns the last visible subnode (recursively) of the argument node. If no argument is given, returns the last visible subnode of the tree.
label(node)
Returns the label of that node, i.e. the first HTML child element
having class TN_label
.
content(node)
Returns the content of that node, i.e. the last HTML child element
having class TN_content
.
nextDisplayedNode(node)
Returns the next tree node in page display order (i.e. next visible node down the page).
previousDisplayedNode(node)
Returns the previous tree node in page display order (i.e. previous visible node up the page).
enclosingNode(elem)
Returns the first tree node that contains the given element (which might be for example a form input).
Manipulations to the tree generate events for which clients can register some handlers, exactly like ordinary HTML events.
Select
/ Deselect
triggered when a node is marked / unmarked as the
currently selected node. Both events are not
triggered immediately, but only after
selectDelay
milliseconds have elapsed :
this is an optimization to avoid too many calls
while the user is navigating quickly through the
nodes; in other words, intermediate nodes
crossed while navigating the tree will not
receive any trigger.
If label selection is associated with
focus (i.e. if tabIndex
was not set
to -1), then selection/deselection events
are also triggered when the user switches
to another desktop window.
Open
/ Close
triggered when a node is opened or closed
BeforeLoadContent
/ AfterLoadContent
triggered before/after a node's content
is loaded from an URL (throug opening the node,
or hitting the Ctrl-R
key) -- see
the section below about dynamic tree
updates).
inspect
triggered when a user calls the inspector for a node (either by hitting the RETURN key or by double-clicking the node's label)
Handlers can access an event
structure,
similar to what is passed to ordinary HTML events;
the entries are:
Event handlers can be registered in several ways:
<div class="TN_node" TN:onOpen="handleOpen(this, treeNavigator)">
The additional attribute is the event name,
prefixed by the constant TN:on
; so in
the example above, a hander is registered for
event Open
.
The string containing handler code is evaluated in a context where some special variables are predefined:
targetNode
the node element
this
the node element (synonym for targetNode
)
treeNavigator
the tree navigator object
event
an event structure as described above
If the string just contains the name of a handler function (i.e. without the parentheses), then that function will be called with a single argument, namely the event structure described above. Therefore
<div class="TN_node" TN:onOpen="handleOpen">
is equivalent to
<div class="TN_node" TN:onOpen="handleOpen(event)">
<div id="theTree" TN:onOpen="handleOpen(targetNode, this)">
Handlers can be registered on the tree element,
exactly like for node elements. The only
difference is that this
is then bound to
the tree element instead of the target node.
treeNavigator.initSubTree(subtree);
Whenever a subtree was added programmatically into the
tree, this method should be called in order to install the
navigation buttons, mouse event handlers and tabbing
behaviour. The initSubTree
method expects to find
at least one TN_label
element within the
subtree.
This method is called automatically when a subtree
is dynamically fetched through the
TN:contentURL
property.