Zapatec.BasicTree

Overview | File | Class | Tree | Index | Help

Zapatec Utils

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## Class Zapatec.BasicTree

    Object
       |
       +--Zapatec.BasicTree

class Zapatec.BasicTree

Defined in tree.js

Field Summary
`<static> Object` | `all` This global variable keeps a "hash table" (that is, a plain JavaScript object) mapping ID-s to references to Zapatec.BasicTree objects.

Constructor Summary
`Zapatec.BasicTree(el, config)` The Zapatec.BasicTree object constructor.

Method Summary
`Object` | `_getTree(tree_id, dont_call)` \internal This function is used when "dynamic initialization" is on.
`void` | `appendChild(parent, newChild, atStart)` Append a child to the start or end of the given parent.
`void` | `collapseAll()` Call this function to collapse all items in the tree.
`Object` | `createItem(li, parent, next_li, level, atStart)` \internal This function walks through a LI element and creates the HTML elements associated with that tree item.
`Object` | `createTree(list, parent, level)` \internal Function that creates a (sub)tree.
`void` | `destroy()` Destroys the tree.
`void` | `expandAll()` Call this function to expand all items in the tree.
`Object` | `getParent(id, mode)` Call to get the parent to append, insert or remove a child either at start or end position or in between two nodes of the (sub-)tree.
`void` | `init(el, config)`
`void` | `insertBefore(newChild, refChild)` A new child can be inserted between two nodes/children or before one node /children at the same tree level.
`void` | `item_addDefaultIcon(item, className)` \internal This function adds a TD element having a certain class attribute which helps having a tree containing icons without defining IMG tags for each item.
`void` | `item_addIcon(item, img)` \internal This function does different things, depending on whether the \b img parameter is passed or not.
`void` | `itemClicked(item_id)` This function gets called from a global event handler when some item was clicked.
`Object` | `makeNode(html, type)` Call this function to create a html element with the optional element type specified.
`void` | `onItemSelect()` Third party code can override this member in order to add an event handler that gets called each time a tree item is selected.
`void` | `removeChild(oldChild)` An old child node in the tree can be removed at any level.
`void` | `sync(item_id)` Call this function to synchronize the tree to a given item.
`void` | `toggleAll()` Call this function to toggle all items in the tree.
`Object` | `toggleItem(item_id, state)` This function toggles an item if the \b state parameter is not specified.
`<static> void` | `onItemToggle()` \internal This is a global event handler that gets called when a tree item is clicked.

Field Detail

### all

    <static> Object all

This global variable keeps a "hash table" (that is, a plain JavaScript object) mapping ID-s to references to Zapatec.BasicTree objects. It's helpful if you want to operate on a tree but you don't want to keep a reference to it. Example: \code // the following makes a tree for the

element var tree = new Zapatec.BasicTree("tree-id"); // ... later var existing_tree = Zapatec.BasicTree.all("tree-id"); // and now we can use \b existing_tree the same as we can use \b tree // the following displays \b true alert(existing_tree == tree); \endcode So in short, this variable remembers values returned by "new Zapatec.BasicTree(...)" in case you didn't.

Constructor Detail

### Zapatec.BasicTree

    Zapatec.BasicTree(el, config)

The Zapatec.BasicTree object constructor. Pass to it the ID of an UL element (or a reference to the element should you have it already) and an optional configuration object. This function creates and initializes the tree widget according to data existent in the nested list, and applies the configuration specified. The configuration object may contain the following options (the following shows default values): \code { hiliteSelectedNode : true, // boolean compact : false, // boolean dynamic : false, // boolean initLevel : false, // false or number defaultIcons : null // null or string } \endcode - hiliteSelectedNode -- if \b false is passed, the tree will not highlight the currently selected node. - compact -- if \b true is passed the tree will work in a "compact" mode; in this mode it automatically closes sections not relevant to the current one. - dynamic -- if \b true is passed the tree will use the "dynamic initialization" technique which greatly improves generation time. Some functionality is not available in this mode until all the tree was generated. In "dynamic" mode the tree is initially collapsed and levels are generated "on the fly" as the end user expands them. You can't retrieve nodes by ID (which implies you can't synchronize to certain nodes) until they have been generated. - initLevel -- when this is a numeric value, it specifies the maximum "expand level" that the tree will use initially. Therefore, if for instance you specify 1 then the tree will be initially expanded one level. Pass here 0 to have the tree fully collapsed, or leave it \b false to have the tree fully expanded. - defaultIcons -- you can pass here a string. If so, all tree items will get an additional TD element containing that string in the \b class attribute. This helps you to include custom default icons without specifying them as IMG tags in the tree. See our examples.

Parameters:

`el` - [string or HTMLElement] -- the UL element

`config` - [Object, optional] -- the configuration options

Method Detail

### _getTree

    Object _getTree(tree_id, dont_call)

\internal This function is used when "dynamic initialization" is on. It retrieves a reference to a subtree if already created, or creates it if it wasn't yet and \b dont_call is \b false (returns null in that case).

Parameters:

`tree_id` - [string] the ID of the subtree

`dont_call` - [boolean] pass true here if you don't want the subtree to be created

Returns:

reference to the tree if it was found or created, null otherwise.

### appendChild

    void appendChild(parent, newChild, atStart)

Append a child to the start or end of the given parent.

Parameters:

`parent` - [HTMLElement] -- reference to a tree node (either as a node at top level or at a subtree level) the new child going to be appended to in the tree.

`newChild` - [HTMLElement] -- reference to an HTML element created of type LI, to which futher HTML elements such UL and LI can be included to generate subtrees.

`atStart` - [boolean, optional] -- true if the child going to be added at the start of the parent.

### collapseAll

    void collapseAll()

Call this function to collapse all items in the tree.

### createItem

    Object createItem(li, parent, next_li, level, atStart)

\internal This function walks through a LI element and creates the HTML elements associated with that tree item. When it encounters an UL element it calls createTree() in order to create the item's subtree. This function may also call item_addIcon() in order to add the +/- buttons or icons present in the item definition as IMG tags, or item_addDefaultIcon() if the tree configuration specifies "defaultIcons" and no IMG tag was present.

Parameters:

`li` - [HTMLElement] -- reference to the LI element

`parent` - [HTMLElement] -- reference to the parent element where the HTML elements should be created

`next_li` - [HTMLLiElement] -- reference to the next LI element, if this is not the last one

`level` - [integer] -- the level of this item in the main tree

`atStart` - [HTMLElement optional] -- reference to the element DIV with a TABLE object that represents the child following the new child added or inserted

Returns:

[HTMLElement] -- a reference to a DIV element holding the HTML elements of the created item

### createTree

    Object createTree(list, parent, level)

\internal Function that creates a (sub)tree. This function walks the UL element, computes and assigns CSS class names and creates HTML elements for a subtree. Each time a LI element is encountered, createItem() is called which effectively creates the item. Beware that createItem() might call back this function in order to create the item's subtree. (so createTree and createItem form an indirect recursion).

Parameters:

`list` - [HTMLElement] -- reference to the UL element

`parent` - [HTMLElement] -- reference to the parent element that should hold the (sub)tree

`level` - [integer] -- the level of this (sub)tree in the main tree.

Returns:

id -- the (sub)tree ID; might be automatically generated.

### destroy

    void destroy()

Destroys the tree. Removes all elements. Does not destroy the Zapatec.BasicTree object itself (actually there's no proper way in JavaScript to do that).

### expandAll

    void expandAll()

Call this function to expand all items in the tree.

### getParent

    Object getParent(id, mode)

Call to get the parent to append, insert or remove a child either at start or end position or in between two nodes of the (sub-)tree. For insert, if the user selects a tree-item that represents the root node of a subtree, then the new child will be inserted outside the subtree, i.e. exactly before the root node of the subtree. However, if the user selects the node that represents one of the children in the subtree, then the new child will be inserted in the subtree under the root. For remove, if the user selects the root node of a subtree, the root node including its children will be removed. If the user selects a node that is not a root node of a subtree, then only that node will be deleted. In the implementation, the p will first retrieve the subtree from Tree.trees. But this is just the object that encapsulates the subtree, not the root of the entire subtree. For insert and remove,

Parameters:

`id` - [String] -- id of the parent the new child will be added to or inserted before/at.

`mode` - [String optional] -- "I" is for inserting a child node. "R" is for removing a child node.

### init

    void init(el, config)

### insertBefore

    void insertBefore(newChild, refChild)

A new child can be inserted between two nodes/children or before one node /children at the same tree level. Inserting the new child before the first node of a tree is allowed but not allowed after the last node of the tree, i.e. end of the tree, except before the last node.

Parameters:

`newChild` - [HTMLElement] -- New child node to be inserted into the tree

`refChild` - [HTMLElement] -- Reference to the child node which the new child node will be inserted before

### item_addDefaultIcon

    void item_addDefaultIcon(item, className)

\internal This function adds a TD element having a certain class attribute which helps having a tree containing icons without defining IMG tags for each item. The class name will be "tgb icon className" (where "className" is the specified parameter). Further, in order to customize the icons, one should add some CSS lines like this: \code div.tree-item td.customIcon { background: url("themes/img/fs/document2.png") no-repeat 0 50%; } div.tree-item-expanded td.customIcon { background: url("themes/img/fs/folder-open.png") no-repeat 0 50%; } div.tree-item-collapsed td.customIcon { background: url("themes/img/fs/folder.png") no-repeat 0 50%; } \endcode As you can see, it's very easy to customize the default icons for a normal tree item (that has no subtrees) or for expanded or collapsed items. For the above example to work, one has to pass { defaultIcons: "customIcon" } in the tree configuration object. This function does nothing if the \b className parameter has a false logical value (i.e. is null).

Parameters:

`item` - [HTMLElement] -- reference to the DIV element holding the item

`className` - -- a string containing the additional class name

### item_addIcon

    void item_addIcon(item, img)

\internal This function does different things, depending on whether the \b img parameter is passed or not. If the \b img is passed, then this function adds it as an icon for the given item. If not passed, this function creates a "+/-" button for the given item.

Parameters:

`item` - [HTMLElement] -- reference to the DIV holding the item elements

`img` - [HTMLImgElement, optional] -- reference to an IMG element; normally one found in the

### itemClicked

    void itemClicked(item_id)

This function gets called from a global event handler when some item was clicked. It selects the item and toggles it if it has a subtree (expands or collapses it).

Parameters:

`item_id` - [string] -- the item ID

### makeNode

    Object makeNode(html, type)

Call this function to create a html element with the optional element type specified. By default, it is a
- element.

Parameters:

`html` - [string, optional] -- html of the node; may include

,
- elements; user is responsible for the content of the html

`type` - [string, optional] -- type of the node to be created

### onItemSelect

    void onItemSelect()

Third party code can override this member in order to add an event handler that gets called each time a tree item is selected. It receives a single string parameter containing the item ID.

### removeChild

    void removeChild(oldChild)

An old child node in the tree can be removed at any level. If the old child node happens to be the root of a subtree, then the entire subtree including child node(s) under the root node will be removed. If the old child node is just an item node without any child node under it as children, then the only node removed is the old child node. Once an item node or a subtree is removed, the node/subtree before and/or after the old node will be joined together, sometimes with tree lines redrawn. The only limitations are that the root node of the top tree is not permitted for removal; the first child node found will be removed if there are more than one tree node with the same id.

Parameters:

`oldChild` - [HTMLElement] -- Old child node to be removed from the tree where it can be an item node without children or a subtree including the old child node as the root.

### sync

    void sync(item_id)

Call this function to synchronize the tree to a given item. This means that all items will be collapsed, except that item and the full path to it.

Parameters:

`item_id` - [string] -- the ID of the item to sync to.

### toggleAll

    void toggleAll()

Call this function to toggle all items in the tree.

### toggleItem

    Object toggleItem(item_id, state)

This function toggles an item if the \b state parameter is not specified. If \b state is \b true then it expands the item, and if \b state is \b false then it collapses the item.

Parameters:

`item_id` - [string] -- the item ID

`state` - [boolean, optional] -- the desired item state

Returns:

a reference to the item element if found, null otherwise

### onItemToggle

    <static> void onItemToggle()

\internal This is a global event handler that gets called when a tree item is clicked. Don't override! ;-)

Overview | File | Class | Tree | Index | Help

Zapatec Utils

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Documentation generated by JSDoc on Thu Aug 16 12:18:39 2007