# Yahoo! UI Library

### TreeView Widget

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

    /**
     * The base class for all tree nodes.  The node's presentation and behavior in
     * response to mouse events is handled in Node subclasses.
     * @namespace YAHOO.widget
     * @class Node
     * @param oData {object} a string or object containing the data that will
     * be used to render this node
     * @param oParent {Node} this node's parent node
     * @param expanded {boolean} the initial expanded/collapsed state
     * @constructor
     */
    YAHOO.widget.Node = function(oData, oParent, expanded) {
        if (oData) { this.init(oData, oParent, expanded); }
    };

    YAHOO.widget.Node.prototype = {

        /**
         * The index for this instance obtained from global counter in YAHOO.widget.TreeView.
         * @property index
         * @type int
         */
        index: 0,

        /**
         * This node's child node collection.
         * @property children
         * @type Node[]
         */
        children: null,

        /**
         * Tree instance this node is part of
         * @property tree
         * @type TreeView
         */
        tree: null,

        /**
         * The data linked to this node.  This can be any object or primitive
         * value, and the data can be used in getNodeHtml().
         * @property data
         * @type object
         */
        data: null,

        /**
         * Parent node
         * @property parent
         * @type Node
         */
        parent: null,

        /**
         * The depth of this node.  We start at -1 for the root node.
         * @property depth
         * @type int
         */
        depth: -1,

        /**
         * The href for the node's label.  If one is not specified, the href will
         * be set so that it toggles the node.
         * @property href
         * @type string
         */
        href: null,

        /**
         * The label href target, defaults to current window
         * @property target
         * @type string
         */
        target: "_self",

        /**
         * The node's expanded/collapsed state
         * @property expanded
         * @type boolean
         */
        expanded: false,

        /**
         * Can multiple children be expanded at once?
         * @property multiExpand
         * @type boolean
         */
        multiExpand: true,

        /**
         * Should we render children for a collapsed node?  It is possible that the
         * implementer will want to render the hidden data...  @todo verify that we
         * need this, and implement it if we do.
         * @property renderHidden
         * @type boolean
         */
        renderHidden: false,

        /**
         * This flag is set to true when the html is generated for this node's
         * children, and set to false when new children are added.
         * @property childrenRendered
         * @type boolean
         */
        childrenRendered: false,

        /**
         * Dynamically loaded nodes only fetch the data the first time they are
         * expanded.  This flag is set to true once the data has been fetched.
         * @property dynamicLoadComplete
         * @type boolean
         */
        dynamicLoadComplete: false,

        /**
         * This node's previous sibling
         * @property previousSibling
         * @type Node
         */
        previousSibling: null,

        /**
         * This node's next sibling
         * @property nextSibling
         * @type Node
         */
        nextSibling: null,

        /**
         * We can set the node up to call an external method to get the child
         * data dynamically.
         * @property _dynLoad
         * @type boolean
         * @private
         */
        _dynLoad: false,

        /**
         * Function to execute when we need to get this node's child data.
         * @property dataLoader
         * @type function
         */
        dataLoader: null,

        /**
         * This is true for dynamically loading nodes while waiting for the
         * callback to return.
         * @property isLoading
         * @type boolean
         */
        isLoading: false,

        /**
         * The toggle/branch icon will not show if this is set to false.  This
         * could be useful if the implementer wants to have the child contain
         * extra info about the parent, rather than an actual node.
         * @property hasIcon
         * @type boolean
         */
        hasIcon: true,

        /**
         * Used to configure what happens when a dynamic load node is expanded
         * and we discover that it does not have children.  By default, it is
         * treated as if it still could have children (plus/minus icon).  Set
         * iconMode to have it display like a leaf node instead.
         * @property iconMode
         * @type int
         */
        iconMode: 0,

        /**
         * The node type
         * @property _type
         * @private
         */
        _type: "Node",

        /*
        spacerPath: "http://us.i1.yimg.com/us.yimg.com/i/space.gif",
        expandedText: "Expanded",
        collapsedText: "Collapsed",
        loadingText: "Loading",
        */

        /**
         * Initializes this node, gets some of the properties from the parent
         * @method init
         * @param oData {object} a string or object containing the data that will
         * be used to render this node
         * @param oParent {Node} this node's parent node
         * @param expanded {boolean} the initial expanded/collapsed state
         */
        init: function(oData, oParent, expanded) {

            this.data       = oData;
            this.children   = [];
            this.index      = YAHOO.widget.TreeView.nodeCount;
            ++YAHOO.widget.TreeView.nodeCount;
            this.expanded   = expanded;
            this.logger     = new YAHOO.widget.LogWriter(this.toString());

            /**
             * The parentChange event is fired when a parent element is applied
             * to the node.  This is useful if you need to apply tree-level
             * properties to a tree that need to happen if a node is moved from
             * one tre to another.
             *
             * @event parentChange
             * @type CustomEvent
             */
            this.createEvent("parentChange", this);

            // oParent should never be null except when we create the root node.
            if (oParent) {
                oParent.appendChild(this);
            }
        },

        /**
         * Certain properties for the node cannot be set until the parent
         * is known. This is called after the node is inserted into a tree.
         * the parent is also applied to this node's children in order to
         * make it possible to move a branch from one tree to another.
         * @method applyParent
         * @param {Node} parentNode this node's parent node
         * @return {boolean} true if the application was successful
         */
        applyParent: function(parentNode) {
            if (!parentNode) {
                return false;
            }

            this.tree   = parentNode.tree;
            this.parent = parentNode;
            this.depth  = parentNode.depth + 1;

            if (!this.href) {
                this.href = "javascript:" + this.getToggleLink();
            }

            if (! this.multiExpand) {
                this.multiExpand = parentNode.multiExpand;
            }

            this.tree.regNode(this);
            parentNode.childrenRendered = false;

            // cascade update existing children
            for (var i=0, len=this.children.length;i<len;++i) {
                this.children[i].applyParent(this);
            }

            this.fireEvent("parentChange");

            return true;
        },

        /**
         * Appends a node to the child collection.
         * @method appendChild
         * @param childNode {Node} the new node
         * @return {Node} the child node
         * @private
         */
        appendChild: function(childNode) {
            if (this.hasChildren()) {
                var sib = this.children[this.children.length - 1];
                sib.nextSibling = childNode;
                childNode.previousSibling = sib;
            }
            this.children[this.children.length] = childNode;
            childNode.applyParent(this);

            return childNode;
        },

        /**
         * Appends this node to the supplied node's child collection
         * @method appendTo
         * @param parentNode {Node} the node to append to.
         * @return {Node} The appended node
         */
        appendTo: function(parentNode) {
            return parentNode.appendChild(this);
        },

        /**
        * Inserts this node before this supplied node
        * @method insertBefore
        * @param node {Node} the node to insert this node before
        * @return {Node} the inserted node
        */
        insertBefore: function(node) {
            this.logger.log("insertBefore: " + node);
            var p = node.parent;
            if (p) {

                if (this.tree) {
                    this.tree.popNode(this);
                }

                var refIndex = node.isChildOf(p);
                //this.logger.log(refIndex);
                p.children.splice(refIndex, 0, this);
                if (node.previousSibling) {
                    node.previousSibling.nextSibling = this;
                }
                this.previousSibling = node.previousSibling;
                this.nextSibling = node;
                node.previousSibling = this;

                this.applyParent(p);
            }

            return this;
        },

        /**
        * Inserts this node after the supplied node
        * @method insertAfter
        * @param node {Node} the node to insert after
        * @return {Node} the inserted node
        */
        insertAfter: function(node) {
            this.logger.log("insertAfter: " + node);
            var p = node.parent;
            if (p) {

                if (this.tree) {
                    this.tree.popNode(this);
                }

                var refIndex = node.isChildOf(p);
                this.logger.log(refIndex);

                if (!node.nextSibling) {
                    return this.appendTo(p);
                }

                p.children.splice(refIndex + 1, 0, this);

                node.nextSibling.previousSibling = this;
                this.previousSibling = node;
                this.nextSibling = node.nextSibling;
                node.nextSibling = this;

                this.applyParent(p);
            }

            return this;
        },

        /**
        * Returns true if the Node is a child of supplied Node
        * @method isChildOf
        * @param parentNode {Node} the Node to check
        * @return {boolean} The node index if this Node is a child of
        *                   supplied Node, else -1.
        * @private
        */
        isChildOf: function(parentNode) {
            if (parentNode && parentNode.children) {
                for (var i=0, len=parentNode.children.length; i<len ; ++i) {
                    if (parentNode.children[i] === this) {
                        return i;
                    }
                }
            }

            return -1;
        },

        /**
         * Returns a node array of this node's siblings, null if none.
         * @method getSiblings
         * @return Node[]
         */
        getSiblings: function() {
            return this.parent.children;
        },

        /**
         * Shows this node's children
         * @method showChildren
         */
        showChildren: function() {
            if (!this.tree.animateExpand(this.getChildrenEl(), this)) {
                if (this.hasChildren()) {
                    this.getChildrenEl().style.display = "";
                }
            }
        },

        /**
         * Hides this node's children
         * @method hideChildren
         */
        hideChildren: function() {
            this.logger.log("hiding " + this.index);

            if (!this.tree.animateCollapse(this.getChildrenEl(), this)) {
                this.getChildrenEl().style.display = "none";
            }
        },

        /**
         * Returns the id for this node's container div
         * @method getElId
         * @return {string} the element id
         */
        getElId: function() {
            return "ygtv" + this.index;
        },

        /**
         * Returns the id for this node's children div
         * @method getChildrenElId
         * @return {string} the element id for this node's children div
         */
        getChildrenElId: function() {
            return "ygtvc" + this.index;
        },

        /**
         * Returns the id for this node's toggle element
         * @method getToggleElId
         * @return {string} the toggel element id
         */
        getToggleElId: function() {
            return "ygtvt" + this.index;
        },

        /*
         * Returns the id for this node's spacer image.  The spacer is positioned
         * over the toggle and provides feedback for screen readers.
         * @method getSpacerId
         * @return {string} the id for the spacer image
         */
        /*
        getSpacerId: function() {
            return "ygtvspacer" + this.index;
        },
        */

        /**
         * Returns this node's container html element
         * @method getEl
         * @return {HTMLElement} the container html element
         */
        getEl: function() {
            return document.getElementById(this.getElId());
        },

        /**
         * Returns the div that was generated for this node's children
         * @method getChildrenEl
         * @return {HTMLElement} this node's children div
         */
        getChildrenEl: function() {
            return document.getElementById(this.getChildrenElId());
        },

        /**
         * Returns the element that is being used for this node's toggle.
         * @method getToggleEl
         * @return {HTMLElement} this node's toggle html element
         */
        getToggleEl: function() {
            return document.getElementById(this.getToggleElId());
        },

        /*
         * Returns the element that is being used for this node's spacer.
         * @method getSpacer
         * @return {HTMLElement} this node's spacer html element
         */
        /*
        getSpacer: function() {
            return document.getElementById( this.getSpacerId() ) || {};
        },
        */

        /*
        getStateText: function() {
            if (this.isLoading) {
                return this.loadingText;
            } else if (this.hasChildren(true)) {
                if (this.expanded) {
                    return this.expandedText;
                } else {
                    return this.collapsedText;
                }
            } else {
                return "";
            }
        },
        */

        /**
         * Generates the link that will invoke this node's toggle method
         * @method getToggleLink
         * @return {string} the javascript url for toggling this node
         */
        getToggleLink: function() {
            return "YAHOO.widget.TreeView.getNode(\'" + this.tree.id + "\'," +
                this.index + ").toggle()";
        },

        /**
         * Hides this nodes children (creating them if necessary), changes the
         * @method collapse
         * toggle style.
         */
        collapse: function() {
            // Only collapse if currently expanded
            if (!this.expanded) { return; }

            // fire the collapse event handler
            var ret = this.tree.onCollapse(this);

            if (false === ret) {
                this.logger.log("Collapse was stopped by the abstract onCollapse");
                return;
            }

            ret = this.tree.fireEvent("collapse", this);

            if (false === ret) {
                this.logger.log("Collapse was stopped by a custom event handler");
                return;
            }

            if (!this.getEl()) {
                this.expanded = false;
                return;
            }

            // hide the child div
            this.hideChildren();
            this.expanded = false;

            this.updateIcon();

            // this.getSpacer().title = this.getStateText();

        },

        /**
         * Shows this nodes children (creating them if necessary), changes the
         * toggle style, and collapses its siblings if multiExpand is not set.
         * @method expand
         */
        expand: function() {
            // Only expand if currently collapsed.
            if (this.expanded) { return; }

            // fire the expand event handler
            var ret = this.tree.onExpand(this);

            if (false === ret) {
                this.logger.log("Expand was stopped by the abstract onExpand");
                return;
            }

            ret = this.tree.fireEvent("expand", this);

            if (false === ret) {
                this.logger.log("Expand was stopped by the custom event handler");
                return;
            }

            if (!this.getEl()) {
                this.expanded = true;
                return;
            }

            if (! this.childrenRendered) {
                this.logger.log("children not rendered yet");
                this.getChildrenEl().innerHTML = this.renderChildren();
            } else {
                this.logger.log("CHILDREN RENDERED");
            }

            this.expanded = true;

            this.updateIcon();

            // this.getSpacer().title = this.getStateText();

            // We do an extra check for children here because the lazy
            // load feature can expose nodes that have no children.

            // if (!this.hasChildren()) {
            if (this.isLoading) {
                this.expanded = false;
                return;
            }

            if (! this.multiExpand) {
                var sibs = this.getSiblings();
                for (var i=0; i<sibs.length; ++i) {
                    if (sibs[i] != this && sibs[i].expanded) {
                        sibs[i].collapse();
                    }
                }
            }

            this.showChildren();
        },

        updateIcon: function() {
            if (this.hasIcon) {
                var el = this.getToggleEl();
                if (el) {
                    el.className = this.getStyle();
                }
            }
        },

        /**
         * Returns the css style name for the toggle
         * @method getStyle
         * @return {string} the css class for this node's toggle
         */
        getStyle: function() {
            // this.logger.log("No children, " + " isDyanmic: " + this.isDynamic() + " expanded: " + this.expanded);
            if (this.isLoading) {
                this.logger.log("returning the loading icon");
                return "ygtvloading";
            } else {
                // location top or bottom, middle nodes also get the top style
                var loc = (this.nextSibling) ? "t" : "l";

                // type p=plus(expand), m=minus(collapase), n=none(no children)
                var type = "n";
                if (this.hasChildren(true) || (this.isDynamic() && !this.getIconMode())) {
                // if (this.hasChildren(true)) {
                    type = (this.expanded) ? "m" : "p";
                }

                // this.logger.log("ygtv" + loc + type);
                return "ygtv" + loc + type;
            }
        },

        /**
         * Returns the hover style for the icon
         * @return {string} the css class hover state
         * @method getHoverStyle
         */
        getHoverStyle: function() {
            var s = this.getStyle();
            if (this.hasChildren(true) && !this.isLoading) {
                s += "h";
            }
            return s;
        },

        /**
         * Recursively expands all of this node's children.
         * @method expandAll
         */
        expandAll: function() {
            for (var i=0;i<this.children.length;++i) {
                var c = this.children[i];
                if (c.isDynamic()) {
                    alert("Not supported (lazy load + expand all)");
                    break;
                } else if (! c.multiExpand) {
                    alert("Not supported (no multi-expand + expand all)");
                    break;
                } else {
                    c.expand();
                    c.expandAll();
                }
            }
        },

        /**
         * Recursively collapses all of this node's children.
         * @method collapseAll
         */
        collapseAll: function() {
            for (var i=0;i<this.children.length;++i) {
                this.children[i].collapse();
                this.children[i].collapseAll();
            }
        },

        /**
         * Configures this node for dynamically obtaining the child data
         * when the node is first expanded.  Calling it without the callback
         * will turn off dynamic load for the node.
         * @method setDynamicLoad
         * @param fmDataLoader {function} the function that will be used 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) {
            if (fnDataLoader) {
                this.dataLoader = fnDataLoader;
                this._dynLoad = true;
            } else {
                this.dataLoader = null;
                this._dynLoad = false;
            }

            if (iconMode) {
                this.iconMode = iconMode;
            }
        },

        /**
         * Evaluates if this node is the root node of the tree
         * @method isRoot
         * @return {boolean} true if this is the root node
         */
        isRoot: function() {
            return (this == this.tree.root);
        },

        /**
         * Evaluates if this node's children should be loaded dynamically.  Looks for
         * the property both in this instance and the root node.  If the tree is
         * defined to load all children dynamically, the data callback function is
         * defined in the root node
         * @method isDynamic
         * @return {boolean} true if this node's children are to be loaded dynamically
         */
        isDynamic: function() {
            var lazy = (!this.isRoot() && (this._dynLoad || this.tree.root._dynLoad));
            // this.logger.log("isDynamic: " + lazy);
            return lazy;
        },

        /**
         * Returns the current icon mode.  This refers to the way childless dynamic
         * load nodes appear.
         * @method getIconMode
         * @return {int} 0 for collapse style, 1 for leaf node style
         */
        getIconMode: function() {
            return (this.iconMode || this.tree.root.iconMode);
        },

        /**
         * Checks if this node has children.  If this node is lazy-loading and the
         * children have not been rendered, we do not know whether or not there
         * are actual children.  In most cases, we need to assume that there are
         * children (for instance, the toggle needs to show the expandable
         * presentation state).  In other times we want to know if there are rendered
         * children.  For the latter, "checkForLazyLoad" should be false.
         * @method hasChildren
         * @param checkForLazyLoad {boolean} should we check for unloaded children?
         * @return {boolean} true if this has children or if it might and we are
         * checking for this condition.
         */
        hasChildren: function(checkForLazyLoad) {
            return ( this.children.length > 0 ||
                    (checkForLazyLoad && this.isDynamic() && !this.dynamicLoadComplete) );
        },

        /**
         * Expands if node is collapsed, collapses otherwise.
         * @method toggle
         */
        toggle: function() {
            if (!this.tree.locked && ( this.hasChildren(true) || this.isDynamic()) ) {
                if (this.expanded) { this.collapse(); } else { this.expand(); }
            }
        },

        /**
         * Returns the markup for this node and its children.
         * @method getHtml
         * @return {string} the markup for this node and its expanded children.
         */
        getHtml: function() {

            this.childrenRendered = false;

            var sb = [];
            sb[sb.length] = '<div class="ygtvitem" id="' + this.getElId() + '">';
            sb[sb.length] = this.getNodeHtml();
            sb[sb.length] = this.getChildrenHtml();
            sb[sb.length] = '</div>';
            return sb.join("");
        },

        /**
         * Called when first rendering the tree.  We always build the div that will
         * contain this nodes children, but we don't render the children themselves
         * unless this node is expanded.
         * @method getChildrenHtml
         * @return {string} the children container div html and any expanded children
         * @private
         */
        getChildrenHtml: function() {

            var sb = [];
            sb[sb.length] = '<div class="ygtvchildren"';
            sb[sb.length] = ' id="' + this.getChildrenElId() + '"';
            if (!this.expanded) {
                sb[sb.length] = ' style="display:none;"';
            }
            sb[sb.length] = '>';

            // Don't render the actual child node HTML unless this node is expanded.
            if ( (this.hasChildren(true) && this.expanded) ||
                    (this.renderHidden && !this.isDynamic()) ) {
                sb[sb.length] = this.renderChildren();
            }

            sb[sb.length] = '</div>';

            return sb.join("");
        },

        /**
         * Generates the markup for the child nodes.  This is not done until the node
         * is expanded.
         * @method renderChildren
         * @return {string} the html for this node's children
         * @private
         */
        renderChildren: function() {

            this.logger.log("rendering children for " + this.index);

            var node = this;

            if (this.isDynamic() && !this.dynamicLoadComplete) {
                this.isLoading = true;
                this.tree.locked = true;

                if (this.dataLoader) {
                    this.logger.log("Using dynamic loader defined for this node");

                    setTimeout(
                        function() {
                            node.dataLoader(node,
                                function() {
                                    node.loadComplete();
                                });
                        }, 10);

                } else if (this.tree.root.dataLoader) {
                    this.logger.log("Using the tree-level dynamic loader");

                    setTimeout(
                        function() {
                            node.tree.root.dataLoader(node,
                                function() {
                                    node.loadComplete();
                                });
                        }, 10);

                } else {
                    this.logger.log("no loader found");
                    return "Error: data loader not found or not specified.";
                }

                return "";

            } else {
                return this.completeRender();
            }
        },

        /**
         * Called when we know we have all the child data.
         * @method completeRender
         * @return {string} children html
         */
        completeRender: function() {
            this.logger.log("completeRender: " + this.index + ", # of children: " + this.children.length);
            var sb = [];

            for (var i=0; i < this.children.length; ++i) {
                // this.children[i].childrenRendered = false;
                sb[sb.length] = this.children[i].getHtml();
            }

            this.childrenRendered = true;

            return sb.join("");
        },

        /**
         * Load complete is the callback function we pass to the data provider
         * in dynamic load situations.
         * @method loadComplete
         */
        loadComplete: function() {
            this.logger.log("loadComplete: " + this.index);
            this.getChildrenEl().innerHTML = this.completeRender();
            this.dynamicLoadComplete = true;
            this.isLoading = false;
            this.expand();
            this.tree.locked = false;
        },

        /**
         * Returns this node's ancestor at the specified depth.
         * @method getAncestor
         * @param {int} depth the depth of the ancestor.
         * @return {Node} the ancestor
         */
        getAncestor: function(depth) {
            if (depth >= this.depth || depth < 0)  {
                this.logger.log("illegal getAncestor depth: " + depth);
                return null;
            }

            var p = this.parent;

            while (p.depth > depth) {
                p = p.parent;
            }

            return p;
        },

        /**
         * Returns the css class for the spacer at the specified depth for
         * this node.  If this node's ancestor at the specified depth
         * has a next sibling the presentation is different than if it
         * does not have a next sibling
         * @method getDepthStyle
         * @param {int} depth the depth of the ancestor.
         * @return {string} the css class for the spacer
         */
        getDepthStyle: function(depth) {
            return (this.getAncestor(depth).nextSibling) ?
                "ygtvdepthcell" : "ygtvblankdepthcell";
        },

        /**
         * Get the markup for the node.  This is designed to be overrided so that we can
         * support different types of nodes.
         * @method getNodeHtml
         * @return {string} The HTML that will render this node.
         */
        getNodeHtml: function() {
            this.logger.log("Generating html");
            return "";
        },

        /**
         * Regenerates the html for this node and its children.  To be used when the
         * node is expanded and new children have been added.
         * @method refresh
         */
        refresh: function() {
            // this.loadComplete();
            this.getChildrenEl().innerHTML = this.completeRender();

            if (this.hasIcon) {
                var el = this.getToggleEl();
                if (el) {
                    el.className = this.getStyle();
                }
            }
        },

        /**
         * Node toString
         * @method toString
         * @return {string} string representation of the node
         */
        toString: function() {
            return "Node (" + this.index + ")";
        }

    };

    YAHOO.augment(YAHOO.widget.Node, YAHOO.util.EventProvider);

Copyright © 2006 Yahoo! Inc. All rights reserved.