/**
* The treeview widget is a generic tree building tool.
* @module treeview
* @title TreeView Widget
* @requires yahoo, event
* @optional animation
* @namespace YAHOO.widget
*/
/**
* Contains the tree view state data and the root node.
*
* @class TreeView
* @uses YAHOO.util.EventProvider
* @constructor
* @param {string|HTMLElement} id The id of the element, or the element
* itself that the tree will be inserted into.
*/
YAHOO.widget.TreeView = function(id) {
if (id) { this.init(id); }
};
YAHOO.widget.TreeView.prototype = {
/**
* The id of tree container element
* @property id
* @type String
*/
id: null,
/**
* The host element for this tree
* @property _el
* @private
*/
_el: null,
/**
* Flat collection of all nodes in this tree. This is a sparse
* array, so the length property can't be relied upon for a
* node count for the tree.
* @property _nodes
* @type Node[]
* @private
*/
_nodes: null,
/**
* We lock the tree control while waiting for the dynamic loader to return
* @property locked
* @type boolean
*/
locked: false,
/**
* The animation to use for expanding children, if any
* @property _expandAnim
* @type string
* @private
*/
_expandAnim: null,
/**
* The animation to use for collapsing children, if any
* @property _collapseAnim
* @type string
* @private
*/
_collapseAnim: null,
/**
* The current number of animations that are executing
* @property _animCount
* @type int
* @private
*/
_animCount: 0,
/**
* The maximum number of animations to run at one time.
* @property maxAnim
* @type int
*/
maxAnim: 2,
/**
* Sets up the animation for expanding children
* @method setExpandAnim
* @param {string} type the type of animation (acceptable values defined
* in YAHOO.widget.TVAnim)
*/
setExpandAnim: function(type) {
if (YAHOO.widget.TVAnim.isValid(type)) {
this._expandAnim = type;
}
},
/**
* Sets up the animation for collapsing children
* @method setCollapseAnim
* @param {string} the type of animation (acceptable values defined in
* YAHOO.widget.TVAnim)
*/
setCollapseAnim: function(type) {
if (YAHOO.widget.TVAnim.isValid(type)) {
this._collapseAnim = type;
}
},
/**
* Perform the expand animation if configured, or just show the
* element if not configured or too many animations are in progress
* @method animateExpand
* @param el {HTMLElement} the element to animate
* @param node {YAHOO.util.Node} the node that was expanded
* @return {boolean} true if animation could be invoked, false otherwise
*/
animateExpand: function(el, node) {
this.logger.log("animating expand");
if (this._expandAnim && this._animCount < this.maxAnim) {
// this.locked = true;
var tree = this;
var a = YAHOO.widget.TVAnim.getAnim(this._expandAnim, el,
function() { tree.expandComplete(node); });
if (a) {
++this._animCount;
this.fireEvent("animStart", {
"node": node,
"type": "expand"
});
a.animate();
}
return true;
}
return false;
},
/**
* Perform the collapse animation if configured, or just show the
* element if not configured or too many animations are in progress
* @method animateCollapse
* @param el {HTMLElement} the element to animate
* @param node {YAHOO.util.Node} the node that was expanded
* @return {boolean} true if animation could be invoked, false otherwise
*/
animateCollapse: function(el, node) {
this.logger.log("animating collapse");
if (this._collapseAnim && this._animCount < this.maxAnim) {
// this.locked = true;
var tree = this;
var a = YAHOO.widget.TVAnim.getAnim(this._collapseAnim, el,
function() { tree.collapseComplete(node); });
if (a) {
++this._animCount;
this.fireEvent("animStart", {
"node": node,
"type": "collapse"
});
a.animate();
}
return true;
}
return false;
},
/**
* Function executed when the expand animation completes
* @method expandComplete
*/
expandComplete: function(node) {
this.logger.log("expand complete: " + this.id);
--this._animCount;
this.fireEvent("animComplete", {
"node": node,
"type": "expand"
});
// this.locked = false;
},
/**
* Function executed when the collapse animation completes
* @method collapseComplete
*/
collapseComplete: function(node) {
this.logger.log("collapse complete: " + this.id);
--this._animCount;
this.fireEvent("animComplete", {
"node": node,
"type": "collapse"
});
// this.locked = false;
},
/**
* Initializes the tree
* @method init
* @parm {string|HTMLElement} id the id of the element that will hold the tree
* @private
*/
init: function(id) {
this.id = id;
if ("string" !== typeof id) {
this._el = id;
this.id = this.generateId(id);
}
/**
* When animation is enabled, this event fires when the animation
* starts
* @event animStart
* @type CustomEvent
* @param {YAHOO.widget.Node} node the node that is expanding/collapsing
* @parm {String} type the type of animation ("expand" or "collapse")
*/
this.createEvent("animStart", this);
/**
* When animation is enabled, this event fires when the animation
* completes
* @event animComplete
* @type CustomEvent
* @param {YAHOO.widget.Node} node the node that is expanding/collapsing
* @parm {String} type the type of animation ("expand" or "collapse")
*/
this.createEvent("animComplete", this);
/**
* Fires when a node is going to be collapsed. Return false to stop
* the collapse.
* @event collapse
* @type CustomEvent
* @param {YAHOO.widget.Node} node the node that is collapsing
*/
this.createEvent("collapse", this);
/**
* Fires after a node is successfully collapsed. This event will not fire
* if the "collapse" event was cancelled.
* @event collapseComplete
* @type CustomEvent
* @param {YAHOO.widget.Node} node the node that was collapsed
*/
this.createEvent("collapseComplete", this);
/**
* Fires when a node is going to be expanded. Return false to stop
* the collapse.
* @event expand
* @type CustomEvent
* @param {YAHOO.widget.Node} node the node that is expanding
*/
this.createEvent("expand", this);
/**
* Fires after a node is successfully expanded. This event will not fire
* if the "expand" event was cancelled.
* @event expandComplete
* @type CustomEvent
* @param {YAHOO.widget.Node} node the node that was expanded
*/
this.createEvent("expandComplete", this);
this._nodes = [];
// store a global reference
YAHOO.widget.TreeView.trees[this.id] = this;
// Set up the root node
this.root = new YAHOO.widget.RootNode(this);
var LW = YAHOO.widget.LogWriter;
this.logger = (LW) ? new LW(this.toString()) : YAHOO;
this.logger.log("tree init: " + this.id);
// YAHOO.util.Event.onContentReady(this.id, this.handleAvailable, this, true);
// YAHOO.util.Event.on(this.id, "click", this.handleClick, this, true);
},
//handleAvailable: function() {
//var Event = YAHOO.util.Event;
//Event.on(this.id,
//},
/**
* Renders the tree boilerplate and visible nodes
* @method draw
*/
draw: function() {
var html = this.root.getHtml();
this.getEl().innerHTML = html;
this.firstDraw = false;
},
/**
* Returns the tree's host element
* @method getEl
* @return {HTMLElement} the host element
*/
getEl: function() {
if (! this._el) {
this._el = document.getElementById(this.id);
}
return this._el;
},
/**
* Nodes register themselves with the tree instance when they are created.
* @method regNode
* @param node {Node} the node to register
* @private
*/
regNode: function(node) {
this._nodes[node.index] = node;
},
/**
* Returns the root node of this tree
* @method getRoot
* @return {Node} the root node
*/
getRoot: function() {
return this.root;
},
/**
* Configures this tree to dynamically load all child data
* @method setDynamicLoad
* @param {function} fnDataLoader the function that will be called to get the data
* @param iconMode {int} configures the icon that is displayed when a dynamic
* load node is expanded the first time without children. By default, the
* "collapse" icon will be used. If set to 1, the leaf node icon will be
* displayed.
*/
setDynamicLoad: function(fnDataLoader, iconMode) {
this.root.setDynamicLoad(fnDataLoader, iconMode);
},
/**
* Expands all child nodes. Note: this conflicts with the "multiExpand"
* node property. If expand all is called in a tree with nodes that
* do not allow multiple siblings to be displayed, only the last sibling
* will be expanded.
* @method expandAll
*/
expandAll: function() {
if (!this.locked) {
this.root.expandAll();
}
},
/**
* Collapses all expanded child nodes in the entire tree.
* @method collapseAll
*/
collapseAll: function() {
if (!this.locked) {
this.root.collapseAll();
}
},
/**
* Returns a node in the tree that has the specified index (this index
* is created internally, so this function probably will only be used
* in html generated for a given node.)
* @method getNodeByIndex
* @param {int} nodeIndex the index of the node wanted
* @return {Node} the node with index=nodeIndex, null if no match
*/
getNodeByIndex: function(nodeIndex) {
var n = this._nodes[nodeIndex];
return (n) ? n : null;
},
/**
* Returns a node that has a matching property and value in the data
* object that was passed into its constructor.
* @method getNodeByProperty
* @param {object} property the property to search (usually a string)
* @param {object} value the value we want to find (usuall an int or string)
* @return {Node} the matching node, null if no match
*/
getNodeByProperty: function(property, value) {
for (var i in this._nodes) {
var n = this._nodes[i];
if (n.data && value == n.data[property]) {
return n;
}
}
return null;
},
/**
* Returns a collection of nodes that have a matching property
* and value in the data object that was passed into its constructor.
* @method getNodesByProperty
* @param {object} property the property to search (usually a string)
* @param {object} value the value we want to find (usuall an int or string)
* @return {Array} the matching collection of nodes, null if no match
*/
getNodesByProperty: function(property, value) {
var values = [];
for (var i in this._nodes) {
var n = this._nodes[i];
if (n.data && value == n.data[property]) {
values.push(n);
}
}
return (values.length) ? values : null;
},
/**
* Removes the node and its children, and optionally refreshes the
* branch of the tree that was affected.
* @method removeNode
* @param {Node} The node to remove
* @param {boolean} autoRefresh automatically refreshes branch if true
* @return {boolean} False is there was a problem, true otherwise.
*/
removeNode: function(node, autoRefresh) {
// Don't delete the root node
if (node.isRoot()) {
return false;
}
// Get the branch that we may need to refresh
var p = node.parent;
if (p.parent) {
p = p.parent;
}
// Delete the node and its children
this._deleteNode(node);
// Refresh the parent of the parent
if (autoRefresh && p && p.childrenRendered) {
p.refresh();
}
return true;
},
/**
* Deletes this nodes child collection, recursively. Also collapses
* the node, and resets the dynamic load flag. The primary use for
* this method is to purge a node and allow it to fetch its data
* dynamically again.
* @method removeChildren
* @param {Node} node the node to purge
*/
removeChildren: function(node) {
this.logger.log("Removing children for " + node);
while (node.children.length) {
this._deleteNode(node.children[0]);
}
node.childrenRendered = false;
node.dynamicLoadComplete = false;
if (node.expanded) {
node.collapse();
} else {
node.updateIcon();
}
},
/**
* Deletes the node and recurses children
* @method _deleteNode
* @private
*/
_deleteNode: function(node) {
// Remove all the child nodes first
this.removeChildren(node);
// Remove the node from the tree
this.popNode(node);
},
/**
* Removes the node from the tree, preserving the child collection
* to make it possible to insert the branch into another part of the
* tree, or another tree.
* @method popNode
* @param {Node} the node to remove
*/
popNode: function(node) {
var p = node.parent;
// Update the parent's collection of children
var a = [];
for (var i=0, len=p.children.length;i<len;++i) {
if (p.children[i] != node) {
a[a.length] = p.children[i];
}
}
p.children = a;
// reset the childrenRendered flag for the parent
p.childrenRendered = false;
// Update the sibling relationship
if (node.previousSibling) {
node.previousSibling.nextSibling = node.nextSibling;
}
if (node.nextSibling) {
node.nextSibling.previousSibling = node.previousSibling;
}
node.parent = null;
node.previousSibling = null;
node.nextSibling = null;
node.tree = null;
// Update the tree's node collection
delete this._nodes[node.index];
},
/**
* TreeView instance toString
* @method toString
* @return {string} string representation of the tree
*/
toString: function() {
return "TreeView " + this.id;
},
/**
* Generates an unique id for an element if it doesn't yet have one
* @method generateId
* @private
*/
generateId: function(el) {
var id = el.id;
if (!id) {
id = "yui-tv-auto-id-" + YAHOO.widget.TreeView.counter;
++YAHOO.widget.TreeView.counter;
}
return id;
},
/**
* Abstract method that is executed when a node is expanded
* @method onExpand
* @param node {Node} the node that was expanded
* @deprecated use treeobj.subscribe("expand") instead
*/
onExpand: function(node) { },
/**
* Abstract method that is executed when a node is collapsed.
* @method onCollapse
* @param node {Node} the node that was collapsed.
* @deprecated use treeobj.subscribe("collapse") instead
*/
onCollapse: function(node) { }
};
YAHOO.augment(YAHOO.widget.TreeView, YAHOO.util.EventProvider);
/**
* Running count of all nodes created in all trees. This is
* used to provide unique identifies for all nodes. Deleting
* nodes does not change the nodeCount.
* @property YAHOO.widget.TreeView.nodeCount
* @type int
* @static
*/
YAHOO.widget.TreeView.nodeCount = 0;
/**
* Global cache of tree instances
* @property YAHOO.widget.TreeView.trees
* @type Array
* @static
* @private
*/
YAHOO.widget.TreeView.trees = [];
/**
* Counter for generating a new unique element id
* @property YAHOO.widget.TreeView.counter
* @static
* @private
*/
YAHOO.widget.TreeView.counter = 0;
/**
* Global method for getting a tree by its id. Used in the generated
* tree html.
* @method YAHOO.widget.TreeView.getTree
* @param treeId {String} the id of the tree instance
* @return {TreeView} the tree instance requested, null if not found.
* @static
*/
YAHOO.widget.TreeView.getTree = function(treeId) {
var t = YAHOO.widget.TreeView.trees[treeId];
return (t) ? t : null;
};
/**
* Global method for getting a node by its id. Used in the generated
* tree html.
* @method YAHOO.widget.TreeView.getNode
* @param treeId {String} the id of the tree instance
* @param nodeIndex {String} the index of the node to return
* @return {Node} the node instance requested, null if not found
* @static
*/
YAHOO.widget.TreeView.getNode = function(treeId, nodeIndex) {
var t = YAHOO.widget.TreeView.getTree(treeId);
return (t) ? t.getNodeByIndex(nodeIndex) : null;
};
/**
* Add a DOM event
* @method YAHOO.widget.TreeView.addHandler
* @param el the elment to bind the handler to
* @param {string} sType the type of event handler
* @param {function} fn the callback to invoke
* @static
*/
YAHOO.widget.TreeView.addHandler = function (el, sType, fn) {
if (el.addEventListener) {
el.addEventListener(sType, fn, false);
} else if (el.attachEvent) {
el.attachEvent("on" + sType, fn);
}
};
/**
* Remove a DOM event
* @method YAHOO.widget.TreeView.removeHandler
* @param el the elment to bind the handler to
* @param {string} sType the type of event handler
* @param {function} fn the callback to invoke
* @static
*/
YAHOO.widget.TreeView.removeHandler = function (el, sType, fn) {
if (el.removeEventListener) {
el.removeEventListener(sType, fn, false);
} else if (el.detachEvent) {
el.detachEvent("on" + sType, fn);
}
};
/**
* Attempts to preload the images defined in the styles used to draw the tree by
* rendering off-screen elements that use the styles.
* @method YAHOO.widget.TreeView.preload
* @param {string} prefix the prefix to use to generate the names of the
* images to preload, default is ygtv
* @static
*/
YAHOO.widget.TreeView.preload = function(e, prefix) {
prefix = prefix || "ygtv";
YAHOO.log("Preloading images: " + prefix, "info", "TreeView");
var styles = ["tn","tm","tmh","tp","tph","ln","lm","lmh","lp","lph","loading"];
// var styles = ["tp"];
var sb = [];
// save the first one for the outer container
for (var i=1; i < styles.length; i=i+1) {
sb[sb.length] = '<span class="' + prefix + styles[i] + '"> </span>';
}
var f = document.createElement("div");
var s = f.style;
s.className = prefix + styles[0];
s.position = "absolute";
s.height = "1px";
s.width = "1px";
s.top = "-1000px";
s.left = "-1000px";
f.innerHTML = sb.join("");
document.body.appendChild(f);
YAHOO.widget.TreeView.removeHandler(window,
"load", YAHOO.widget.TreeView.preload);
};
YAHOO.widget.TreeView.addHandler(window,
"load", YAHOO.widget.TreeView.preload);