src/widgets/tree/TreeNode.js

   1 /*!
   2  * Ext JS Library 3.2.0
   3  * Copyright(c) 2006-2010 Ext JS, Inc.
   4  * licensing@extjs.com
   5  * http://www.extjs.com/license
   6  */
   7 /**
   8  * @class Ext.tree.TreeNode
   9  * @extends Ext.data.Node
  10  * @cfg {String} text The text for this node
  11  * @cfg {Boolean} expanded true to start the node expanded
  12  * @cfg {Boolean} allowDrag False to make this node undraggable if {@link #draggable} = true (defaults to true)
  13  * @cfg {Boolean} allowDrop False if this node cannot have child nodes dropped on it (defaults to true)
  14  * @cfg {Boolean} disabled true to start the node disabled
  15  * @cfg {String} icon The path to an icon for the node. The preferred way to do this
  16  * is to use the cls or iconCls attributes and add the icon via a CSS background image.
  17  * @cfg {String} cls A css class to be added to the node
  18  * @cfg {String} iconCls A css class to be added to the nodes icon element for applying css background images
  19  * @cfg {String} href URL of the link used for the node (defaults to #)
  20  * @cfg {String} hrefTarget target frame for the link
  21  * @cfg {Boolean} hidden True to render hidden. (Defaults to false).
  22  * @cfg {String} qtip An Ext QuickTip for the node
  23  * @cfg {Boolean} expandable If set to true, the node will always show a plus/minus icon, even when empty
  24  * @cfg {String} qtipCfg An Ext QuickTip config for the node (used instead of qtip)
  25  * @cfg {Boolean} singleClickExpand True for single click expand on this node
  26  * @cfg {Function} uiProvider A UI <b>class</b> to use for this node (defaults to Ext.tree.TreeNodeUI)
  27  * @cfg {Boolean} checked True to render a checked checkbox for this node, false to render an unchecked checkbox
  28  * (defaults to undefined with no checkbox rendered)
  29  * @cfg {Boolean} draggable True to make this node draggable (defaults to false)
  30  * @cfg {Boolean} isTarget False to not allow this node to act as a drop target (defaults to true)
  31  * @cfg {Boolean} allowChildren False to not allow this node to have child nodes (defaults to true)
  32  * @cfg {Boolean} editable False to not allow this node to be edited by an {@link Ext.tree.TreeEditor} (defaults to true)
  33  * @constructor
  34  * @param {Object/String} attributes The attributes/config for the node or just a string with the text for the node
  35  */
  36 Ext.tree.TreeNode = function(attributes){
  37     attributes = attributes || {};
  38     if(Ext.isString(attributes)){
  39         attributes = {text: attributes};
  40     }
  41     this.childrenRendered = false;
  42     this.rendered = false;
  43     Ext.tree.TreeNode.superclass.constructor.call(this, attributes);
  44     this.expanded = attributes.expanded === true;
  45     this.isTarget = attributes.isTarget !== false;
  46     this.draggable = attributes.draggable !== false && attributes.allowDrag !== false;
  47     this.allowChildren = attributes.allowChildren !== false && attributes.allowDrop !== false;
  48
  49     /**
  50      * Read-only. The text for this node. To change it use <code>{@link #setText}</code>.
  51      * @type String
  52      */
  53     this.text = attributes.text;
  54     /**
  55      * True if this node is disabled.
  56      * @type Boolean
  57      */
  58     this.disabled = attributes.disabled === true;
  59     /**
  60      * True if this node is hidden.
  61      * @type Boolean
  62      */
  63     this.hidden = attributes.hidden === true;
  64
  65     this.addEvents(
  66         /**
  67         * @event textchange
  68         * Fires when the text for this node is changed
  69         * @param {Node} this This node
  70         * @param {String} text The new text
  71         * @param {String} oldText The old text
  72         */
  73         'textchange',
  74         /**
  75         * @event beforeexpand
  76         * Fires before this node is expanded, return false to cancel.
  77         * @param {Node} this This node
  78         * @param {Boolean} deep
  79         * @param {Boolean} anim
  80         */
  81         'beforeexpand',
  82         /**
  83         * @event beforecollapse
  84         * Fires before this node is collapsed, return false to cancel.
  85         * @param {Node} this This node
  86         * @param {Boolean} deep
  87         * @param {Boolean} anim
  88         */
  89         'beforecollapse',
  90         /**
  91         * @event expand
  92         * Fires when this node is expanded
  93         * @param {Node} this This node
  94         */
  95         'expand',
  96         /**
  97         * @event disabledchange
  98         * Fires when the disabled status of this node changes
  99         * @param {Node} this This node
 100         * @param {Boolean} disabled
 101         */
 102         'disabledchange',
 103         /**
 104         * @event collapse
 105         * Fires when this node is collapsed
 106         * @param {Node} this This node
 107         */
 108         'collapse',
 109         /**
 110         * @event beforeclick
 111         * Fires before click processing. Return false to cancel the default action.
 112         * @param {Node} this This node
 113         * @param {Ext.EventObject} e The event object
 114         */
 115         'beforeclick',
 116         /**
 117         * @event click
 118         * Fires when this node is clicked
 119         * @param {Node} this This node
 120         * @param {Ext.EventObject} e The event object
 121         */
 122         'click',
 123         /**
 124         * @event checkchange
 125         * Fires when a node with a checkbox's checked property changes
 126         * @param {Node} this This node
 127         * @param {Boolean} checked
 128         */
 129         'checkchange',
 130         /**
 131         * @event beforedblclick
 132         * Fires before double click processing. Return false to cancel the default action.
 133         * @param {Node} this This node
 134         * @param {Ext.EventObject} e The event object
 135         */
 136         'beforedblclick',
 137         /**
 138         * @event dblclick
 139         * Fires when this node is double clicked
 140         * @param {Node} this This node
 141         * @param {Ext.EventObject} e The event object
 142         */
 143         'dblclick',
 144         /**
 145         * @event contextmenu
 146         * Fires when this node is right clicked
 147         * @param {Node} this This node
 148         * @param {Ext.EventObject} e The event object
 149         */
 150         'contextmenu',
 151         /**
 152         * @event beforechildrenrendered
 153         * Fires right before the child nodes for this node are rendered
 154         * @param {Node} this This node
 155         */
 156         'beforechildrenrendered'
 157     );
 158
 159     var uiClass = this.attributes.uiProvider || this.defaultUI || Ext.tree.TreeNodeUI;
 160
 161     /**
 162      * Read-only. The UI for this node
 163      * @type TreeNodeUI
 164      */
 165     this.ui = new uiClass(this);
 166 };
 167 Ext.extend(Ext.tree.TreeNode, Ext.data.Node, {
 168     preventHScroll : true,
 169     /**
 170      * Returns true if this node is expanded
 171      * @return {Boolean}
 172      */
 173     isExpanded : function(){
 174         return this.expanded;
 175     },
 176
 177 /**
 178  * Returns the UI object for this node.
 179  * @return {TreeNodeUI} The object which is providing the user interface for this tree
 180  * node. Unless otherwise specified in the {@link #uiProvider}, this will be an instance
 181  * of {@link Ext.tree.TreeNodeUI}
 182  */
 183     getUI : function(){
 184         return this.ui;
 185     },
 186
 187     getLoader : function(){
 188         var owner;
 189         return this.loader || ((owner = this.getOwnerTree()) && owner.loader ? owner.loader : (this.loader = new Ext.tree.TreeLoader()));
 190     },
 191
 192     // private override
 193     setFirstChild : function(node){
 194         var of = this.firstChild;
 195         Ext.tree.TreeNode.superclass.setFirstChild.call(this, node);
 196         if(this.childrenRendered && of && node != of){
 197             of.renderIndent(true, true);
 198         }
 199         if(this.rendered){
 200             this.renderIndent(true, true);
 201         }
 202     },
 203
 204     // private override
 205     setLastChild : function(node){
 206         var ol = this.lastChild;
 207         Ext.tree.TreeNode.superclass.setLastChild.call(this, node);
 208         if(this.childrenRendered && ol && node != ol){
 209             ol.renderIndent(true, true);
 210         }
 211         if(this.rendered){
 212             this.renderIndent(true, true);
 213         }
 214     },
 215
 216     // these methods are overridden to provide lazy rendering support
 217     // private override
 218     appendChild : function(n){
 219         if(!n.render && !Ext.isArray(n)){
 220             n = this.getLoader().createNode(n);
 221         }
 222         var node = Ext.tree.TreeNode.superclass.appendChild.call(this, n);
 223         if(node && this.childrenRendered){
 224             node.render();
 225         }
 226         this.ui.updateExpandIcon();
 227         return node;
 228     },
 229
 230     // private override
 231     removeChild : function(node, destroy){
 232         this.ownerTree.getSelectionModel().unselect(node);
 233         Ext.tree.TreeNode.superclass.removeChild.apply(this, arguments);
 234         // only update the ui if we're not destroying
 235         if(!destroy){
 236             // if it's been rendered remove dom node
 237             if(node.ui.rendered){
 238                 node.ui.remove();
 239             }
 240             if(this.childNodes.length < 1){
 241                 this.collapse(false, false);
 242             }else{
 243                 this.ui.updateExpandIcon();
 244             }
 245             if(!this.firstChild && !this.isHiddenRoot()){
 246                 this.childrenRendered = false;
 247             }
 248         }
 249         return node;
 250     },
 251
 252     // private override
 253     insertBefore : function(node, refNode){
 254         if(!node.render){
 255             node = this.getLoader().createNode(node);
 256         }
 257         var newNode = Ext.tree.TreeNode.superclass.insertBefore.call(this, node, refNode);
 258         if(newNode && refNode && this.childrenRendered){
 259             node.render();
 260         }
 261         this.ui.updateExpandIcon();
 262         return newNode;
 263     },
 264
 265     /**
 266      * Sets the text for this node
 267      * @param {String} text
 268      */
 269     setText : function(text){
 270         var oldText = this.text;
 271         this.text = this.attributes.text = text;
 272         if(this.rendered){ // event without subscribing
 273             this.ui.onTextChange(this, text, oldText);
 274         }
 275         this.fireEvent('textchange', this, text, oldText);
 276     },
 277
 278     /**
 279      * Triggers selection of this node
 280      */
 281     select : function(){
 282         var t = this.getOwnerTree();
 283         if(t){
 284             t.getSelectionModel().select(this);
 285         }
 286     },
 287
 288     /**
 289      * Triggers deselection of this node
 290      * @param {Boolean} silent (optional) True to stop selection change events from firing.
 291      */
 292     unselect : function(silent){
 293         var t = this.getOwnerTree();
 294         if(t){
 295             t.getSelectionModel().unselect(this, silent);
 296         }
 297     },
 298
 299     /**
 300      * Returns true if this node is selected
 301      * @return {Boolean}
 302      */
 303     isSelected : function(){
 304         var t = this.getOwnerTree();
 305         return t ? t.getSelectionModel().isSelected(this) : false;
 306     },
 307
 308     /**
 309      * Expand this node.
 310      * @param {Boolean} deep (optional) True to expand all children as well
 311      * @param {Boolean} anim (optional) false to cancel the default animation
 312      * @param {Function} callback (optional) A callback to be called when
 313      * expanding this node completes (does not wait for deep expand to complete).
 314      * Called with 1 parameter, this node.
 315      * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the callback is executed. Defaults to this TreeNode.
 316      */
 317     expand : function(deep, anim, callback, scope){
 318         if(!this.expanded){
 319             if(this.fireEvent('beforeexpand', this, deep, anim) === false){
 320                 return;
 321             }
 322             if(!this.childrenRendered){
 323                 this.renderChildren();
 324             }
 325             this.expanded = true;
 326             if(!this.isHiddenRoot() && (this.getOwnerTree().animate && anim !== false) || anim){
 327                 this.ui.animExpand(function(){
 328                     this.fireEvent('expand', this);
 329                     this.runCallback(callback, scope || this, [this]);
 330                     if(deep === true){
 331                         this.expandChildNodes(true);
 332                     }
 333                 }.createDelegate(this));
 334                 return;
 335             }else{
 336                 this.ui.expand();
 337                 this.fireEvent('expand', this);
 338                 this.runCallback(callback, scope || this, [this]);
 339             }
 340         }else{
 341            this.runCallback(callback, scope || this, [this]);
 342         }
 343         if(deep === true){
 344             this.expandChildNodes(true);
 345         }
 346     },
 347
 348     runCallback : function(cb, scope, args){
 349         if(Ext.isFunction(cb)){
 350             cb.apply(scope, args);
 351         }
 352     },
 353
 354     isHiddenRoot : function(){
 355         return this.isRoot && !this.getOwnerTree().rootVisible;
 356     },
 357
 358     /**
 359      * Collapse this node.
 360      * @param {Boolean} deep (optional) True to collapse all children as well
 361      * @param {Boolean} anim (optional) false to cancel the default animation
 362      * @param {Function} callback (optional) A callback to be called when
 363      * expanding this node completes (does not wait for deep expand to complete).
 364      * Called with 1 parameter, this node.
 365      * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the callback is executed. Defaults to this TreeNode.
 366      */
 367     collapse : function(deep, anim, callback, scope){
 368         if(this.expanded && !this.isHiddenRoot()){
 369             if(this.fireEvent('beforecollapse', this, deep, anim) === false){
 370                 return;
 371             }
 372             this.expanded = false;
 373             if((this.getOwnerTree().animate && anim !== false) || anim){
 374                 this.ui.animCollapse(function(){
 375                     this.fireEvent('collapse', this);
 376                     this.runCallback(callback, scope || this, [this]);
 377                     if(deep === true){
 378                         this.collapseChildNodes(true);
 379                     }
 380                 }.createDelegate(this));
 381                 return;
 382             }else{
 383                 this.ui.collapse();
 384                 this.fireEvent('collapse', this);
 385                 this.runCallback(callback, scope || this, [this]);
 386             }
 387         }else if(!this.expanded){
 388             this.runCallback(callback, scope || this, [this]);
 389         }
 390         if(deep === true){
 391             var cs = this.childNodes;
 392             for(var i = 0, len = cs.length; i < len; i++) {
 393                 cs[i].collapse(true, false);
 394             }
 395         }
 396     },
 397
 398     // private
 399     delayedExpand : function(delay){
 400         if(!this.expandProcId){
 401             this.expandProcId = this.expand.defer(delay, this);
 402         }
 403     },
 404
 405     // private
 406     cancelExpand : function(){
 407         if(this.expandProcId){
 408             clearTimeout(this.expandProcId);
 409         }
 410         this.expandProcId = false;
 411     },
 412
 413     /**
 414      * Toggles expanded/collapsed state of the node
 415      */
 416     toggle : function(){
 417         if(this.expanded){
 418             this.collapse();
 419         }else{
 420             this.expand();
 421         }
 422     },
 423
 424     /**
 425      * Ensures all parent nodes are expanded, and if necessary, scrolls
 426      * the node into view.
 427      * @param {Function} callback (optional) A function to call when the node has been made visible.
 428      * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the callback is executed. Defaults to this TreeNode.
 429      */
 430     ensureVisible : function(callback, scope){
 431         var tree = this.getOwnerTree();
 432         tree.expandPath(this.parentNode ? this.parentNode.getPath() : this.getPath(), false, function(){
 433             var node = tree.getNodeById(this.id);  // Somehow if we don't do this, we lose changes that happened to node in the meantime
 434             tree.getTreeEl().scrollChildIntoView(node.ui.anchor);
 435             this.runCallback(callback, scope || this, [this]);
 436         }.createDelegate(this));
 437     },
 438
 439     /**
 440      * Expand all child nodes
 441      * @param {Boolean} deep (optional) true if the child nodes should also expand their child nodes
 442      */
 443     expandChildNodes : function(deep){
 444         var cs = this.childNodes;
 445         for(var i = 0, len = cs.length; i < len; i++) {
 446                 cs[i].expand(deep);
 447         }
 448     },
 449
 450     /**
 451      * Collapse all child nodes
 452      * @param {Boolean} deep (optional) true if the child nodes should also collapse their child nodes
 453      */
 454     collapseChildNodes : function(deep){
 455         var cs = this.childNodes;
 456         for(var i = 0, len = cs.length; i < len; i++) {
 457                 cs[i].collapse(deep);
 458         }
 459     },
 460
 461     /**
 462      * Disables this node
 463      */
 464     disable : function(){
 465         this.disabled = true;
 466         this.unselect();
 467         if(this.rendered && this.ui.onDisableChange){ // event without subscribing
 468             this.ui.onDisableChange(this, true);
 469         }
 470         this.fireEvent('disabledchange', this, true);
 471     },
 472
 473     /**
 474      * Enables this node
 475      */
 476     enable : function(){
 477         this.disabled = false;
 478         if(this.rendered && this.ui.onDisableChange){ // event without subscribing
 479             this.ui.onDisableChange(this, false);
 480         }
 481         this.fireEvent('disabledchange', this, false);
 482     },
 483
 484     // private
 485     renderChildren : function(suppressEvent){
 486         if(suppressEvent !== false){
 487             this.fireEvent('beforechildrenrendered', this);
 488         }
 489         var cs = this.childNodes;
 490         for(var i = 0, len = cs.length; i < len; i++){
 491             cs[i].render(true);
 492         }
 493         this.childrenRendered = true;
 494     },
 495
 496     // private
 497     sort : function(fn, scope){
 498         Ext.tree.TreeNode.superclass.sort.apply(this, arguments);
 499         if(this.childrenRendered){
 500             var cs = this.childNodes;
 501             for(var i = 0, len = cs.length; i < len; i++){
 502                 cs[i].render(true);
 503             }
 504         }
 505     },
 506
 507     // private
 508     render : function(bulkRender){
 509         this.ui.render(bulkRender);
 510         if(!this.rendered){
 511             // make sure it is registered
 512             this.getOwnerTree().registerNode(this);
 513             this.rendered = true;
 514             if(this.expanded){
 515                 this.expanded = false;
 516                 this.expand(false, false);
 517             }
 518         }
 519     },
 520
 521     // private
 522     renderIndent : function(deep, refresh){
 523         if(refresh){
 524             this.ui.childIndent = null;
 525         }
 526         this.ui.renderIndent();
 527         if(deep === true && this.childrenRendered){
 528             var cs = this.childNodes;
 529             for(var i = 0, len = cs.length; i < len; i++){
 530                 cs[i].renderIndent(true, refresh);
 531             }
 532         }
 533     },
 534
 535     beginUpdate : function(){
 536         this.childrenRendered = false;
 537     },
 538
 539     endUpdate : function(){
 540         if(this.expanded && this.rendered){
 541             this.renderChildren();
 542         }
 543     },
 544
 545     //inherit docs
 546     destroy : function(silent){
 547         if(silent === true){
 548             this.unselect(true);
 549         }
 550         Ext.tree.TreeNode.superclass.destroy.call(this, silent);
 551         Ext.destroy(this.ui, this.loader);
 552         this.ui = this.loader = null;
 553     },
 554
 555     // private
 556     onIdChange : function(id){
 557         this.ui.onIdChange(id);
 558     }
 559 });
 560
 561 Ext.tree.TreePanel.nodeTypes.node = Ext.tree.TreeNode;