# Yahoo! UI Library

### TreeView Widget

Yahoo! UI Library > treeview > TreeView.js (source view)

    /**
     * The treeview widget is a generic tree building tool.
     * @module treeview
     * @title TreeView Widget
     * @requires yahoo
     * @optional animation
     * @namespace YAHOO.widget
     */

    /**
     * Contains the tree view state data and the root node.
     *
     * @class TreeView
     * @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
         * @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 expanded.  Return false to stop
             * the expand.
             * @event collapse
             * @type CustomEvent
             * @param {YAHOO.widget.Node} node the node that is expanding/collapsing
             */
            this.createEvent("collapse", this);

            /**
             * Fires when a node is going to be collapsed.  Return false to stop
             * the collapse.
             * @event expand
             * @type CustomEvent
             * @param {YAHOO.widget.Node} node the node that is expanding/collapsing
             */
            this.createEvent("expand", 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);

            this.logger = new YAHOO.widget.LogWriter(this.toString());

            this.logger.log("tree init: " + 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);

    /**
     * Count of all nodes in all trees
     * @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(prefix) {
        prefix = prefix || "ygtv";
        var styles = ["tn","tm","tmh","tp","tph","ln","lm","lmh","lp","lph","loading"];

        var sb = [];

        for (var i = 0; i < styles.length; ++i) {
            sb[sb.length] = '<span class="' + prefix + styles[i] + '">&#160;</span>';
        }

        var f = document.createElement("div");
        var s = f.style;
        s.position = "absolute";
        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);

Copyright © 2006 Yahoo! Inc. All rights reserved.