COOLjsTree Documentation

Foreword

This document covers most of the creation and initialization process for COOLjsTree and COOLjsTree Professional from CoolDev.Com. While this document describes data structures needed by these scripts and the way all these things can be glued together to fit in your pages, you will not find wide variety of complete samples here: you can find them in your COOLjsTree or COOLjsTree Professional package in the "demos" or "samples" subdirectories. Also, this document does not cover license, support and purchase issues - answers to these questions you can find in the FAQ.

COOLjsTree Professional has all the functions that are included in COOLjsTree, and offers many additional, but generally scripts are compatible. Input data and format specifications for both these scripts are very alike, and farther all references to "tree" will mean both COOLjsTree and COOLjsTree Professional if not specified otherwise.

Authors

Author of this document is Alex Kunin (alx@cooldev.com), representative of CoolDev.com technical support team (jssupport@cooldev.com). If you have comments, questions, brilliant ideas or you want to criticize something then don't hesitate contacting me.

General information
Required components and installation process
Complete samples
Reference

General information

Scripts covered in this document allow you to create and use tree-like visual representation of hierarchical data like menus, site navigation, file system structure, etc. But tree's functionality is not limited to these applications. Visiting our galleries (for the COOLjsTree and COOLjsTree Professional) will help you to get general idea of the possibilities that tree provides.

Basically tree is a program written in JavaScript - programming language commonly used in web development. No JavaScript knowledge is required to use the tree - this is not too hard to modify existing tree (e.g. complete sample which is explained in this document) to get what you want. But for advanced tree usage it is strongly recommended to have basic JavaScript skills.

To create and test tree you need some text editor and some browser. Tree runs on most of the available browsers that provide JavaScript and CSS support. These browsers are: Internet Explorer 4 and above (limited support for version 3 is also available), Netscape Navigator 4.x, Netscape Navigator 6 and above, Mozilla 0.9.4 and above, Opera 5 and above. To create and/or modify tree's structure and format definitions you need some text editor (Notepad for Windows' users is a good one to start). More complex systems for site management such as FrontPage, InterDev, and Dreamweaver also can be used.

Required components and installation process

To get the tree working you need following components:

tree script itself (cooltree.js or cooltreepro.js; these files are can be found in the "js" subdirectory in the corresponding packages);
tree structure - captions and URLs for every node;
tree format - definitions that regulate tree's appearance and behavior;
HTML page which will include the tree.

You can place these components into separate files (next section tells how to do this) or mix them into a single HTML document. No matter how things are glued together initialization sequence must be in the HTML code. This sequence is different for COOLjsTree and COOLjsTree Professional.

COOLjsTree must be initialized like this:

This snippet must be placed somewhere in the HTML code, but not inside any containers other than <BODY> - this is very important. By not following this rule you'll get garbled tree shrunk into a single line. The best place for this code is immediately before the closing </BODY> tag - it is safe to place initialization there. (Technical details: COOLjsTree's constructor will generate HTML code - set of DIVs, and then this code will be written to the document flow using "document.write()" method. So, putting the constructor call in a wrong place will lead to undesired side effects.)

As you can see code contains four custom elements which apply to both COOLjsTree and COOLjsTree Professional:

myTree - name of the variable that will hold reference to the newly created tree; this variable can be used to access tree at runtime, e.g. to expand or collapse branches;
"tree1" - name of the tree; if you have several trees on the page then you have to name them differently, e.g. "tree1", "tree2" and so on; it is recommended to compose these names using alphanumeric characters because there are many places where names will be used: CSS class names, images' and layers' identifiers - some browsers do not allow to have fancy symbols here (e.g. Opera 5 does not understand CSS class names with underscores);
TREE1_NODES - JavaScript array with nodes (you can find sample farther in this section, reference is in the corresponding section); because this is a JavaScript construct it's definition must be placed into <SCRIPT> tag or into the separate file;
TREE1_FORMAT - JavaScript array with format definition (again, sample is farther in this section, and reference is in the corresponding section below); similar to TREE1_NODES this array must be placed either into <SCRIPT> tag or separated into a file.

COOLjsTree Professional has couple of additional initialization statements:

If your tree is positioned absolutely (see "Tree's format" reference for details) then you can place all these code pieces into single <SCRIPT> statement just before the </BODY> - outside of any containers. For relative positioning mode following rules must be honored: "new COOLjsTreePRO(...)" part can be placed anywhere before the "init()"; at the place where you want to see your tree (e.g. inside a TD cell) "init()" part must be placed; "RedrawAllTrees()" should be at the very end of file before the closing </BODY> tag or in the "onload" event handler:

Here is minimum HTML document with COOLjsTree inside:

<html>
    <body>
        <script type="text/javascript" src="cooltree.js"></script>
        <script type="text/javascript">
// Part 1 - Tree nodes definition
var TREE1_NODES = [
    ['Site 1', 'http://www.site1.net/', null],
    ['Site 2', 'http://www.site2.net/', null],
    ['Site 3', 'http://www.site3.net/', null]
];

// Part 2 - Tree format
var TREE1_FORMAT = [
    10,               // 0. x coordinate
    10,               // 1. y coordinate
    true,             // 2. button images flag
    [                 // 3. button images:
      "img/c.gif",    //    collapsed,
      "img/e.gif",    //    expanded,
      "img/b.gif"     //    blank
    ],
    [ 16, 16, 0],     // 4. button images size: width,
                      // height, and indentation for
                      // childless nodes
    true,             // 5. folder images flag
    [                 // 6. folder images:
        "img/fc.gif", //    closed,
        "img/fe.gif", //    opened,
        "img/d.gif"   //    document
    ],
    [ 16, 16],        // 7. folder images size: width, height
    [ 0, 16, 32 ],    // 8. indentation for each level
    "white",          // 9. background color for the whole
                      // tree
    "clsNode",        // 10. default CSS class for nodes
    [ "cl1", "cl2" ], // 11. CSS classes for each level
    false,            // 12. single branch mode flag
    [ 0, 0 ]          // 13. item padding and spacing
];

// Part 3 - Initialization code
var myTree = new COOLjsTree("tree1", TREE1_NODES, TREE1_FORMAT);
        </script>
    </body>
</html>

COOLjsTree Professional has more formatting options, its initialization sequence has more statements:

<html>
    <body>
        <script type="text/javascript" src="cooltreepro.js"></script>
        <script type="text/javascript">
// Part 1 - Tree nodes definitionvar TREE1_NODES = [
    ['Site 1', 'http://www.site1.net/', null],
    ['Site 2', 'http://www.site2.net/', null],
    ['Site 3', 'http://www.site3.net/', null]
];

// Part 2 - Tree format
var TREE1_FORMAT = [
    10,                        //  0. x coordinate
    10,                        //  1. y coordinate
    true,                      //  2. button images flag
    [                          //  3. button images:
        "img/c.gif",           //     collapsed,
        "img/e.gif",           //     expanded,
        "img/b.gif"            //     blank
    ],
    [ 16, 16, 0],              //  4. button images size:
                               //     width, height, and
                               //     indentation for
                               //     childless nodes
    true,                      //  5. folder images flag
    [                          //  6. folder images:
        "img/fc.gif",          //     closed,
        "img/fe.gif",          //     opened,
        "img/d.gif"            //     document
    ],
    [ 16, 16],                 //  7. folder images size:
                               //     width, height
    [ 0, 16, 32 ],             //  8. indentation for each
                               //     level
    "white",                   //  9. background color for
                               //     the whole tree
    "clsNode",                 // 10. default CSS class for
                               //     nodes
    [ "cl1", "cl2" ],          // 11. CSS classes for each
                               //     level
    false,                     // 12. single branch mode flag
    [ 0, 0 ],                  // 13. item padding and
                               //     spacing
// ---- additional formatting options ----
    true,                      // 14. explorer-like mode flag
    [                          // 15. images for
                               //     explorer-like mode:
        "img/folder.gif",      // folder,
        "img/folderopen.gif",  // opened folder,
        "img/page.gif",        // page,
        "img/minus.gif",       // button in opened state,
        "img/minusbottom.gif", // same without bottom line,
        "img/plus.gif",        // button in closed state,
        "img/plusbottom.gif",  // same without bottom line,
        "img/line.gif",        // vertical line,
        "img/join.gif",        // three-way join,
        "img/joinbottom.gif"   // two-way join
    ],
    [ 19, 16 ],                // 16. images' size for
                               //     explorer-like mode
    false,                     // 17. state saving feature
                               //     flag
    true,                      // 18. relative positioning
                               //     flag
    [ 180, 150 ],              // 19. initial width and
                               //     height for relative
                               //     positioning mode
    false,                     // 20. resizable background
                               //     for relative
                               //     positioning mode
    true,                      // 21. selected node
                               //     highlighting mode flag
    [                          // 22. attributes for selected
                               //     node:
        "white",               //     background color for
                               //     unselected nodes,
        "#FF0000",             //     same for selected node,
        "clsSelected",         //     CSS class(es) for
                               //     selected node(es),
        "clsExpanded"          //     optional CSS class(es)
                               //     for expanded node(es)
    ],
    300,                       // 23. text wrapping margin
                               //     ("0" means "do not
                               //     wrap")
    "top"                      // 24. vertical alignment for
                               //     buttons and icons
                               //     (applies to trees with
                               //     non-zero text wrapping
                               //     and explorer-like mode
                               //     set to false
];

// Part 3 - Initialization code
var myTree = new COOLjsTreePRO("tree1", TREE1_NODES, TREE1_FORMAT);
myTree.init();
RedrawAllTrees();
        </script>
    </body>
</html>

Detailed information about all these formatting options and data structures is given in the "Reference" section.

Complete samples

If you plan to include same tree into many pages from your site then it is good idea to split samples from previous section into several files. Here is typical set of files:

tree1_nodes.js - contains TREE1_NODES variable - tree's structure;
tree1_format.js - contains TREE1_FORMAT variable - tree's format definition;
cooltree.css - CSS classes for the tree;
cooltree.js or cooltreepro.js - the tree itself;
images - your tree probably contains button or folder images, or it is in explorer-like mode, and it needs some graphical files.

Some HTML code is also needed, of course.

Here are two complete samples which contain all the files listed above: COOLjsTree and COOLjsTree Professional. These are good points to start from: .js files are commented, and you will not get lost. So, download these .zip files, unpack them somewhere, add cooltree.js and cooltreepro.js, and have fun.

Reference

This section contains reference for various parts of COOLjsTree and COOLjsTree Professional: nodes array, tree format array, and API - list of available functions, methods, properties, and event handlers.

Node definition
Tree format
API

Node definition

File "tree_nodes.js" contains an array of nodes. Each node in its turn is also an array, and it consists of the following elements:

optional ID;
caption;
URL (or "null");
name of the target frame (or "null");
optional format specifier (COOLjsTree Professional only).

All other elements in the node's array are considered to be children of that node. Node's definiton is recursive, and every child can be defined using same format.

ID parameter must be specified in the following way:

[{id:123}, ...

Optional format specifier uses following syntax:

..., {format:{ ...node formatting options, see below... }, ...

Available node formatting options:

"expanded" - boolean flag that specifies initial node's state;
"folders" - individual list of node's folder images (format matches option #3 in the tree_format.js);
"buttons" - individual list of node's button images (format matches option #6 in the tree_format.js);
"eimages" - individual list of node's images for explorer-like mode (format matches option #15 in the tree_format.js);
"isFolder" - boolean flag; if it is true, then this particular node will look like a folder even if it does not have childern.
any event handler declartion (see API below), e.g.:
..., {format:{
    caption_onclick:function (node) {
        alert(node.getCaption());
    }
}, ...

These options apply to COOLjsTree Professional only. You can use only those image formatting options that were enabled in the tree_format.js, e.g. if tree is in explorer-like mode then only "eimages" options will be honored, and if these were enabled folder images but not button images, then "button" formatting option will be ignored.

Samples of individual nodes:

Minimal node - no URL (when clicked, this node will not cause browser to navigate somewhere), no target frame, no ID, and no formatting options:
['My node', null, null],
Node with ID:
[{id:75}, 'My node', null, null],
Node which will be expanded initially:
['My node', null, null, {format:{expanded:true}}],
Node with individual set of folder images:
['My node', null, null, {format:{folders:[ 'fc2.gif', 'fe2.gif', 'sd.gif']}}],
Node with URL and target frame specified:
['My node', 'some_page.html', 'mainFrame'],
Node with children:
['Parent node', null, null,
    ['Child 1', null, null],
    ['Child 2', null, null],
    ['Child 3', null, null]
],
Node with children and grandchildren, initially expanded:
['Parent node', null, null, {format:{expanded:true}},
    ['Child 1', null, null],
    ['Child 2', null, null, {format:{expanded:true}},
    ['Grand child 1', null, null],
    ['Grand child 2', null, null],
    ['Grand child 2', null, null]
    ],
    ['Child 3', null, null]
],
Folder node without children:
['Parent node', null, null, {format:{isFolder:true}}],

Tree format

Both COOLjsTree and COOLjsTree Professional have the following formatting options:

integer, X coordinate of the tree: it is relative to conatiner in the relative positioning mode, and it is absolute otherwise;
integer, Y coordinate of the tree: same as previous;
boolean, button images flag: it true then tree will have clickable button images;
array of strings, button images: if previous option is enabled, then this array will be used to derermine button images, e.g.:
[ 'c.gif', 'e.gif', 'b.gif'],
1. c.gif - button in collapsed state: ;
2. e.gif - button in expanded state: ;
3. b.gif - blank image, needed for alignment.
array of integers: width and height of button images, and indentation for childless nodes;
boolean, folder images flag: it true then tree will have folder images;
array of strings, folder images: if previous option is enabled, then this array will be used to derermine folder images, e.g.:
[ 'fc.gif', 'fe.gif', 'd.gif'],
1. fc.gif - image for collapsed nodes with children: ;
2. fe.gif - image for expanded nodes with children: ;
3. d.gif - image for nodes without children: .
array of integers: width and height of folder images;
array of integers, indentation for each level; e.g.:
[ 16, 32, 48 ],
Nodes at level 0 (top-level nodes) will have 16 pixels indentation, level 1 will be shifted by 32 pixels, level 2 - 48 pixels, other levels will be shifted by amount of pixels calulated by multiplying level number by identation for level zero, i.e. level 3 will be idented by 48 pixels, level 4 - 64 pixels, and so on.
string, background color for the tree; if it is blank (i.e. ""), then background will be transparent;
string, default CSS class name for all nodes: this class will be applied to the node's layer;
array of strings, CSS class names for every level, e.g.:
[ 'clsLevel1', 'clsLevel2' ],
Nodes at level 0 will have "clsLevel1" class, level 1 will have "clsLevel2" class, and all other nodes will have class specified in the previous option.
boolean, single branch mode flag: if true then tree will always have only one branch opened, and when user expands some other branch, all other nodes will collapse;
array of integers, item padding and spacing.

COOLjsTree Professional has additional formatting options:

boolean, explorer-like mode flag: if true then tree will have lines and joins - like in most of computer appplications like Explorer or other file managers;
array of strings, list of images for explorer-like mode, e.g.:
[ "img/folder.gif", "img/folderopen.gif", "img/page.gif", "img/minus.gif", "img/minusbottom.gif", "img/plus.gif", "img/plusbottom.gif", "img/line.gif", "img/join.gif", "img/joinbottom.gif" ],
1. - folder;
2. - opened folder;
3. - page;
4. - button in opened state;
5. - same without bottom line;
6. - button in closed state;
7. - same without bottom line;
8. - vertical line;
9. - three-way join;
10. - two-way join.
If explorer-like mode is enabled then options #2-#8 will be ignored.
array of integer, width and height of images for explorer-like mode, e.g.:
[ 19, 16 ],
boolean, state saving feature flag: if true then tree will automatically store to and restore from cookies its state;
boolean, relative positioning flag: if true then tree will be positioned relatively to its container, and options #0 and #1 will be relative to that container;
array of integers, initial width and height of the tree in relative positioning mode;
boolean, resizable background for relative positioning mode: if true then width and height specified in the previous option will grow as tree expands and shkink when it collapses;
boolean, selected node highlighting mode flag: if true then selected node (i.e. node that was clicked by user) will be highlighted;
array of strings, attributes for selected node: first element defines background color for unhighlighted nodes, second - same for selected node, and third element specifies CSS class for selected node:
[ "white", "#FF0000", "clsSelected" ]
There is optional fourth element: CSS class for expanded node. Also, both CSS classes (third and fourth elements) can be arrays - in this case they will specify different values for different levels (the very first value will be default one, i.e. it will be used for these levels which do not have their own CSS classes). E.g.:
[
    "white", "#FF0000",
    [
        "clsSelected1",
        "clsSelected2",
        "clsSelected3"
    ],
    [
        "clsExpanded1",
        "clsExpanded2",
        "clsExpanded3"
    ],
]
"Selected" class takes precedence over "Expanded" one, i.e. expanded and selected node will have "Expanded" class (if any).
integer, text wrapping margin in pixels; actually, this is width of the tree - it will never exceed specified value; 0 means "do not wrap" or "no width limit";
string, one of the following: "top", "middle", "bottom"; if previous option is not zero, then this one specifies vertical alignment for icons and buttons.

API

All listed API entries apply to both Standard and Professional unless specified otherwise.

Global variables and functions
CTExpand(treeName, index)	Global COOLjsTree's function that expands node with given index in the tree with given name.
RedrawAllTrees()	Redraws all COOLjsTree Professional instances on the page. Important part of the initialization sequence, must present either before the or in the body's "onload" event handler.
window.CTrees	Every COOLjsTree Professional instance registers itself in this associative array using own name as key. So, to access tree named "myTree" you can use expressions like "window.CTrees['myTree']" or "window.CTrees.myTree". Also, using this variable you can access tree across frames.
window.NTrees	Has same functionality as window.CTrees but applies to COOLjsTree.
Tree's properties
name	Holds tree name - same string that was passed as first parameter to tree's constructor ("new COOLjsTree...").
Nodes	Array of node objects. It holds all nodes in the tree, and their order is the same as if you would read nodes in the tree_nodes.js from left to right and from top to bottom. Properties and methods for these node objects are described below. Important note: for Professional version it is strongly recommended to use nodeByIndex() function instead of Nodes property.
jsPath	String which hold a JavaScript expression. That expression can be used to construct event handler body for setTimeout() or similar functions. Usually looks like the following: window.CTrees['myTree'] Typical usage is: window.setInterval(myTree.jsPath + '.expandNode(0)', 1000); Applies to Professional version only.
Tree's methods
getRoot()	Returns root node (invisible node which is present in every tree). Applies to Professional version only.
getSelectedNode()	Returns currently selected node (or null if none available). Applies to Professional version only.
ensureVisible(index)	Expands (i.e. calls expandNode with aproriate indexes) all ancestors of the node with specified index.
collapseAll(node)	Collapses all nodes, i.e. only top-level nodes will be visible. If optional 'node' (node object, e.g. returned by nodeByName method) parameter is given, then only descendants of this node will be collapsed.
draw()	Redraws the tree, i.e. moves all nodes in their places, draws visible node and hides invisible (collapsed) ones. With COOLjsTree Professional 2.5.4 and above you should never call this method directly since tree will be refreshed automagically after calls like expandNode and moveTo. This autorefresh will be optimized, i.e. three consequent calls to expandNode will cause only a single refresh.
expandAll(node)	Redraws all nodes, i.e. makes all nodes visible. If optional 'node' (node object, e.g. returned by nodeByName method) parameter is given, then only descendants of this node will be expanded.
expandNode(index, noRedraw, select)	Expands node with the given index. If "noRedraw" parameter is true then this call does not redraw the tree. If "select" is true then node's index will be passed to "selectNode()" method. In Professional version this method also sets/resets CSS class for expanded node (if one was specified in the option #22). Note: COOLjsTree does not support "noRedraw" and "select" parameters.
init()	Generates and writes all HTML code neede by tree. COOLjsTree calls this method automatically (calling it second time will cause errors), and COOLjsTree Professional does not: you have to call it manually - more details you can find the "Required components" sections.
moveTo(x, y)	Moves tree to specified coordinates, but does not redraws it - you have to call "draw()" method manually. Does not apply to COOLjsTree Professional.
nodeByID(id)	Returns the first node object which corresponds to the specified ID which must be defined in the following way: [<u>{id:123}</u>, 'Caption', 'Url.html', ...], RegExp object can be used as ID (Professional version only).
nodeByName(caption)	Returns the first node object which corresponds to the specified caption, i.e. node's caption field in the tree_nodes.js equals to the "caption" parameter of this method. RegExp object can be used as caption (Professional version only).
nodeByURL(url)	Returns the first node object which corresponds to the specified URL, i.e. node's URL field in the tree_nodes.js equals to the "url" parameter of this method. RegExp object can be used as URL (Professional version only).
nodeByIndex(index)	Returns node object with specified index. Applies to Professional version only.
selectNode(index)	Selects node with the given index. Does not do anything useful for the COOLjsTree, but in the Professional version this method clears highlighting from previously selected node and applies special background and CSS class to the newly selected node (as option #22 specifies).
Tree's event handlers
ondraw()	If tree's property "ondraw" contains reference to function, then this function will be called whenever tree redraws, i.e. its draw() method is called by user or automagically.
caption_onclick(node) caption_onmouseover(node) caption_onmouseout(node) image_onclick(node) image_onmouseover(node) image_onmouseout(node) button_onclick(node) button_onmouseover(node) button_onmouseout(node)	These events will be fired when corresponding event will occur within a tree element. E.g. following code will show a message when user clicks node's caption: var tree = new COOLjsTreePRO(...); tree.caption_onclick = function (node) { alert('Node was clicked: ' + node.getCaption(); } Note: all these event handlers must be assigned before the init() call.
Node's properties
index	Index of the node (see tree's property "Nodes").
jsPath	Has meaning similar to the same property of the tree object. Applies to Professional version only.
expanded	Boolean flag that indicates if node is expanded (true) or collapsed (false).
children	Array that holds references to children of the node.
Node's methods
getTree()	Returns tree object which owns the node. Applies to Professional version only.
getParent()	Returns parent node object (root node has null parent). Applies to Professional version only.
getNumberOfChildren()	Returns number of child nodes.
getChild(n)	Returns n'th child node.
getId() getCaption() getUrl() getTarget() getFormat()	Return node's ID, caption, URL, target, and format fields as they were specified in tree_nodes.js file. Applies to Professional version only.
setCaption(value) setUrl(value) setTarget(value)	Dynamically change caption, URL, and target. These methods automagically redraw the tree. Applies to Professional version only.
hasChildren()	Returns "true" if node has children and "false" otherwise.
hideChildren()	Hides node itself and all of its children.
getMinorIndex()	Returns index of the node from its parent's point of view. Primarily used with addNode() method. Applies to Professional version only.
addNode(minorIndex, rawDefinition)	Adds new child node and returns its minor index (it can be different from the minorIndex argument if it was out of range). E.g.: node.addNode( 2, ['My new node', null, null, ['Some child', null, null] ] ); Code snippet above inserts new node with one child. That node will be inserted between second and third child. If minorIndex is 0 or less, then node will be inserted as first child. If minorIndex is greater than number of children, then new node will be inserted as last child. Applies to Professional version only.
recreate(rawDefinition, reuseChildren)	Recreates node using specified definition. If reuseChildren is true, then children will not be recreated, and child nodes within rawDefinition will be ignored. Applies to Professional version only.
deleteNode(minorIndex)	Deletes specifed child node. Applies to Professional version only.
level()	Returns non-negative integer number - level of the node. Top-level iz zero.
getLayer()	Returns platform dependent layer object which corresponds to the node. Note: this object may become invalid due to optimizations. It is not recommended to store references to it. Instead, store a reference to the node itself, and then cal getLayer() when needed. Applies to Professional version only.