3 * Copyright(c) 2006-2009 Ext JS, LLC
5 * http://www.extjs.com/license
8 * @class Ext.tree.TreePanel
\r
10 * <p>The TreePanel provides tree-structured UI representation of tree-structured data.</p>
\r
11 * <p>{@link Ext.tree.TreeNode TreeNode}s added to the TreePanel may each contain metadata
\r
12 * used by your application in their {@link Ext.tree.TreeNode#attributes attributes} property.</p>
\r
13 * <p><b>A TreePanel must have a {@link #root} node before it is rendered.</b> This may either be
\r
14 * specified using the {@link #root} config option, or using the {@link #setRootNode} method.
\r
15 * <p>An example of tree rendered to an existing div:</p><pre><code>
\r
16 var tree = new Ext.tree.TreePanel({
\r
17 renderTo: 'tree-div',
\r
22 containerScroll: true,
\r
24 // auto create TreeLoader
\r
25 dataUrl: 'get-nodes.php',
\r
35 tree.getRootNode().expand();
\r
37 * <p>The example above would work with a data packet similar to this:</p><pre><code>
\r
40 "id": "source\/adapter",
\r
48 "id": "source\/debug.js",
\r
53 * <p>An example of tree within a Viewport:</p><pre><code>
\r
59 title: 'Navigation',
\r
64 loader: new Ext.tree.TreeLoader(),
\r
65 root: new Ext.tree.AsyncTreeNode({
\r
68 text: 'Menu Option 1',
\r
71 text: 'Menu Option 2',
\r
74 text: 'Menu Option 3',
\r
80 click: function(n) {
\r
81 Ext.Msg.alert('Navigation Tree Click', 'You clicked: "' + n.attributes.text + '"');
\r
87 // remaining code not shown ...
\r
92 * @cfg {Ext.tree.TreeNode} root The root node for the tree.
\r
93 * @cfg {Boolean} rootVisible <tt>false</tt> to hide the root node (defaults to <tt>true</tt>)
\r
94 * @cfg {Boolean} lines <tt>false</tt> to disable tree lines (defaults to <tt>true</tt>)
\r
95 * @cfg {Boolean} enableDD <tt>true</tt> to enable drag and drop
\r
96 * @cfg {Boolean} enableDrag <tt>true</tt> to enable just drag
\r
97 * @cfg {Boolean} enableDrop <tt>true</tt> to enable just drop
\r
98 * @cfg {Object} dragConfig Custom config to pass to the {@link Ext.tree.TreeDragZone} instance
\r
99 * @cfg {Object} dropConfig Custom config to pass to the {@link Ext.tree.TreeDropZone} instance
\r
100 * @cfg {String} ddGroup The DD group this TreePanel belongs to
\r
101 * @cfg {Boolean} ddAppendOnly <tt>true</tt> if the tree should only allow append drops (use for trees which are sorted)
\r
102 * @cfg {Boolean} ddScroll <tt>true</tt> to enable body scrolling
\r
103 * @cfg {Boolean} containerScroll <tt>true</tt> to register this container with ScrollManager
\r
104 * @cfg {Boolean} hlDrop <tt>false</tt> to disable node highlight on drop (defaults to the value of {@link Ext#enableFx})
\r
105 * @cfg {String} hlColor The color of the node highlight (defaults to <tt>'C3DAF9'</tt>)
\r
106 * @cfg {Boolean} animate <tt>true</tt> to enable animated expand/collapse (defaults to the value of {@link Ext#enableFx})
\r
107 * @cfg {Boolean} singleExpand <tt>true</tt> if only 1 node per branch may be expanded
\r
108 * @cfg {Object} selModel A tree selection model to use with this TreePanel (defaults to an {@link Ext.tree.DefaultSelectionModel})
\r
109 * @cfg {Boolean} trackMouseOver <tt>false</tt> to disable mouse over highlighting
\r
110 * @cfg {Ext.tree.TreeLoader} loader A {@link Ext.tree.TreeLoader} for use with this TreePanel
\r
111 * @cfg {String} pathSeparator The token used to separate sub-paths in path strings (defaults to <tt>'/'</tt>)
\r
112 * @cfg {Boolean} useArrows <tt>true</tt> to use Vista-style arrows in the tree (defaults to <tt>false</tt>)
\r
113 * @cfg {String} requestMethod The HTTP request method for loading data (defaults to the value of {@link Ext.Ajax#method}).
\r
116 * @param {Object} config
\r
119 Ext.tree.TreePanel = Ext.extend(Ext.Panel, {
\r
120 rootVisible : true,
\r
121 animate : Ext.enableFx,
\r
124 hlDrop : Ext.enableFx,
\r
125 pathSeparator : '/',
\r
128 * @cfg {Array} bubbleEvents
\r
129 * <p>An array of events that, when fired, should be bubbled to any parent container.
\r
130 * See {@link Ext.util.Observable#enableBubble}.
\r
131 * Defaults to <tt>[]</tt>.
\r
135 initComponent : function(){
\r
136 Ext.tree.TreePanel.superclass.initComponent.call(this);
\r
138 if(!this.eventModel){
\r
139 this.eventModel = new Ext.tree.TreeEventModel(this);
\r
142 // initialize the loader
\r
143 var l = this.loader;
\r
145 l = new Ext.tree.TreeLoader({
\r
146 dataUrl: this.dataUrl,
\r
147 requestMethod: this.requestMethod
\r
149 }else if(Ext.isObject(l) && !l.load){
\r
150 l = new Ext.tree.TreeLoader(l);
\r
154 this.nodeHash = {};
\r
157 * The root node of this tree.
\r
158 * @type Ext.tree.TreeNode
\r
164 this.setRootNode(r);
\r
172 * Fires when a new child node is appended to a node in this tree.
\r
173 * @param {Tree} tree The owner tree
\r
174 * @param {Node} parent The parent node
\r
175 * @param {Node} node The newly appended node
\r
176 * @param {Number} index The index of the newly appended node
\r
181 * Fires when a child node is removed from a node in this tree.
\r
182 * @param {Tree} tree The owner tree
\r
183 * @param {Node} parent The parent node
\r
184 * @param {Node} node The child node removed
\r
189 * Fires when a node is moved to a new location in the tree
\r
190 * @param {Tree} tree The owner tree
\r
191 * @param {Node} node The node moved
\r
192 * @param {Node} oldParent The old parent of this node
\r
193 * @param {Node} newParent The new parent of this node
\r
194 * @param {Number} index The index it was moved to
\r
199 * Fires when a new child node is inserted in a node in this tree.
\r
200 * @param {Tree} tree The owner tree
\r
201 * @param {Node} parent The parent node
\r
202 * @param {Node} node The child node inserted
\r
203 * @param {Node} refNode The child node the node was inserted before
\r
207 * @event beforeappend
\r
208 * Fires before a new child is appended to a node in this tree, return false to cancel the append.
\r
209 * @param {Tree} tree The owner tree
\r
210 * @param {Node} parent The parent node
\r
211 * @param {Node} node The child node to be appended
\r
215 * @event beforeremove
\r
216 * Fires before a child is removed from a node in this tree, return false to cancel the remove.
\r
217 * @param {Tree} tree The owner tree
\r
218 * @param {Node} parent The parent node
\r
219 * @param {Node} node The child node to be removed
\r
223 * @event beforemovenode
\r
224 * Fires before a node is moved to a new location in the tree. Return false to cancel the move.
\r
225 * @param {Tree} tree The owner tree
\r
226 * @param {Node} node The node being moved
\r
227 * @param {Node} oldParent The parent of the node
\r
228 * @param {Node} newParent The new parent the node is moving to
\r
229 * @param {Number} index The index it is being moved to
\r
233 * @event beforeinsert
\r
234 * Fires before a new child is inserted in a node in this tree, return false to cancel the insert.
\r
235 * @param {Tree} tree The owner tree
\r
236 * @param {Node} parent The parent node
\r
237 * @param {Node} node The child node to be inserted
\r
238 * @param {Node} refNode The child node the node is being inserted before
\r
243 * @event beforeload
\r
244 * Fires before a node is loaded, return false to cancel
\r
245 * @param {Node} node The node being loaded
\r
250 * Fires when a node is loaded
\r
251 * @param {Node} node The node that was loaded
\r
255 * @event textchange
\r
256 * Fires when the text for a node is changed
\r
257 * @param {Node} node The node
\r
258 * @param {String} text The new text
\r
259 * @param {String} oldText The old text
\r
263 * @event beforeexpandnode
\r
264 * Fires before a node is expanded, return false to cancel.
\r
265 * @param {Node} node The node
\r
266 * @param {Boolean} deep
\r
267 * @param {Boolean} anim
\r
269 'beforeexpandnode',
\r
271 * @event beforecollapsenode
\r
272 * Fires before a node is collapsed, return false to cancel.
\r
273 * @param {Node} node The node
\r
274 * @param {Boolean} deep
\r
275 * @param {Boolean} anim
\r
277 'beforecollapsenode',
\r
279 * @event expandnode
\r
280 * Fires when a node is expanded
\r
281 * @param {Node} node The node
\r
285 * @event disabledchange
\r
286 * Fires when the disabled status of a node changes
\r
287 * @param {Node} node The node
\r
288 * @param {Boolean} disabled
\r
292 * @event collapsenode
\r
293 * Fires when a node is collapsed
\r
294 * @param {Node} node The node
\r
298 * @event beforeclick
\r
299 * Fires before click processing on a node. Return false to cancel the default action.
\r
300 * @param {Node} node The node
\r
301 * @param {Ext.EventObject} e The event object
\r
306 * Fires when a node is clicked
\r
307 * @param {Node} node The node
\r
308 * @param {Ext.EventObject} e The event object
\r
312 * @event containerclick
\r
313 * Fires when the tree container is clicked
\r
314 * @param {Tree} this
\r
315 * @param {Ext.EventObject} e The event object
\r
319 * @event checkchange
\r
320 * Fires when a node with a checkbox's checked property changes
\r
321 * @param {Node} this This node
\r
322 * @param {Boolean} checked
\r
326 * @event beforedblclick
\r
327 * Fires before double click processing on a node. Return false to cancel the default action.
\r
328 * @param {Node} node The node
\r
329 * @param {Ext.EventObject} e The event object
\r
334 * Fires when a node is double clicked
\r
335 * @param {Node} node The node
\r
336 * @param {Ext.EventObject} e The event object
\r
340 * @event containerdblclick
\r
341 * Fires when the tree container is double clicked
\r
342 * @param {Tree} this
\r
343 * @param {Ext.EventObject} e The event object
\r
345 'containerdblclick',
\r
347 * @event contextmenu
\r
348 * Fires when a node is right clicked. To display a context menu in response to this
\r
349 * event, first create a Menu object (see {@link Ext.menu.Menu} for details), then add
\r
350 * a handler for this event:<pre><code>
\r
351 new Ext.tree.TreePanel({
\r
352 title: 'My TreePanel',
\r
353 root: new Ext.tree.AsyncTreeNode({
\r
356 { text: 'Child node 1', leaf: true },
\r
357 { text: 'Child node 2', leaf: true }
\r
360 contextMenu: new Ext.menu.Menu({
\r
363 text: 'Delete Node'
\r
366 itemclick: function(item) {
\r
368 case 'delete-node':
\r
369 var n = item.parentMenu.contextNode;
\r
370 if (n.parentNode) {
\r
379 contextmenu: function(node, e) {
\r
380 // Register the context node with the menu so that a Menu Item's handler function can access
\r
381 // it via its {@link Ext.menu.BaseItem#parentMenu parentMenu} property.
\r
383 var c = node.getOwnerTree().contextMenu;
\r
384 c.contextNode = node;
\r
385 c.showAt(e.getXY());
\r
390 * @param {Node} node The node
\r
391 * @param {Ext.EventObject} e The event object
\r
395 * @event containercontextmenu
\r
396 * Fires when the tree container is right clicked
\r
397 * @param {Tree} this
\r
398 * @param {Ext.EventObject} e The event object
\r
400 'containercontextmenu',
\r
402 * @event beforechildrenrendered
\r
403 * Fires right before the child nodes for a node are rendered
\r
404 * @param {Node} node The node
\r
406 'beforechildrenrendered',
\r
409 * Fires when a node starts being dragged
\r
410 * @param {Ext.tree.TreePanel} this
\r
411 * @param {Ext.tree.TreeNode} node
\r
412 * @param {event} e The raw browser event
\r
417 * Fires when a drag operation is complete
\r
418 * @param {Ext.tree.TreePanel} this
\r
419 * @param {Ext.tree.TreeNode} node
\r
420 * @param {event} e The raw browser event
\r
425 * Fires when a dragged node is dropped on a valid DD target
\r
426 * @param {Ext.tree.TreePanel} this
\r
427 * @param {Ext.tree.TreeNode} node
\r
428 * @param {DD} dd The dd it was dropped on
\r
429 * @param {event} e The raw browser event
\r
433 * @event beforenodedrop
\r
434 * Fires when a DD object is dropped on a node in this tree for preprocessing. Return false to cancel the drop. The dropEvent
\r
435 * passed to handlers has the following properties:<br />
\r
436 * <ul style="padding:5px;padding-left:16px;">
\r
437 * <li>tree - The TreePanel</li>
\r
438 * <li>target - The node being targeted for the drop</li>
\r
439 * <li>data - The drag data from the drag source</li>
\r
440 * <li>point - The point of the drop - append, above or below</li>
\r
441 * <li>source - The drag source</li>
\r
442 * <li>rawEvent - Raw mouse event</li>
\r
443 * <li>dropNode - Drop node(s) provided by the source <b>OR</b> you can supply node(s)
\r
444 * to be inserted by setting them on this object.</li>
\r
445 * <li>cancel - Set this to true to cancel the drop.</li>
\r
446 * <li>dropStatus - If the default drop action is cancelled but the drop is valid, setting this to true
\r
447 * will prevent the animated 'repair' from appearing.</li>
\r
449 * @param {Object} dropEvent
\r
454 * Fires after a DD object is dropped on a node in this tree. The dropEvent
\r
455 * passed to handlers has the following properties:<br />
\r
456 * <ul style="padding:5px;padding-left:16px;">
\r
457 * <li>tree - The TreePanel</li>
\r
458 * <li>target - The node being targeted for the drop</li>
\r
459 * <li>data - The drag data from the drag source</li>
\r
460 * <li>point - The point of the drop - append, above or below</li>
\r
461 * <li>source - The drag source</li>
\r
462 * <li>rawEvent - Raw mouse event</li>
\r
463 * <li>dropNode - Dropped node(s).</li>
\r
465 * @param {Object} dropEvent
\r
469 * @event nodedragover
\r
470 * Fires when a tree node is being targeted for a drag drop, return false to signal drop not allowed. The dragOverEvent
\r
471 * passed to handlers has the following properties:<br />
\r
472 * <ul style="padding:5px;padding-left:16px;">
\r
473 * <li>tree - The TreePanel</li>
\r
474 * <li>target - The node being targeted for the drop</li>
\r
475 * <li>data - The drag data from the drag source</li>
\r
476 * <li>point - The point of the drop - append, above or below</li>
\r
477 * <li>source - The drag source</li>
\r
478 * <li>rawEvent - Raw mouse event</li>
\r
479 * <li>dropNode - Drop node(s) provided by the source.</li>
\r
480 * <li>cancel - Set this to true to signal drop not allowed.</li>
\r
482 * @param {Object} dragOverEvent
\r
486 if(this.singleExpand){
\r
487 this.on('beforeexpandnode', this.restrictExpand, this);
\r
492 proxyNodeEvent : function(ename, a1, a2, a3, a4, a5, a6){
\r
493 if(ename == 'collapse' || ename == 'expand' || ename == 'beforecollapse' || ename == 'beforeexpand' || ename == 'move' || ename == 'beforemove'){
\r
494 ename = ename+'node';
\r
496 // args inline for performance while bubbling events
\r
497 return this.fireEvent(ename, a1, a2, a3, a4, a5, a6);
\r
502 * Returns this root node for this tree
\r
505 getRootNode : function(){
\r
510 * Sets the root node for this tree. If the TreePanel has already rendered a root node, the
\r
511 * previous root node (and all of its descendants) are destroyed before the new root node is rendered.
\r
512 * @param {Node} node
\r
515 setRootNode : function(node){
\r
516 Ext.destroy(this.root);
\r
517 if(!node.render){ // attributes passed
\r
518 node = this.loader.createNode(node);
\r
521 node.ownerTree = this;
\r
522 node.isRoot = true;
\r
523 this.registerNode(node);
\r
524 if(!this.rootVisible){
\r
525 var uiP = node.attributes.uiProvider;
\r
526 node.ui = uiP ? new uiP(node) : new Ext.tree.RootTreeNodeUI(node);
\r
528 if (this.innerCt) {
\r
529 this.innerCt.update('');
\r
530 this.afterRender();
\r
536 * Gets a node in this tree by its id
\r
537 * @param {String} id
\r
540 getNodeById : function(id){
\r
541 return this.nodeHash[id];
\r
545 registerNode : function(node){
\r
546 this.nodeHash[node.id] = node;
\r
550 unregisterNode : function(node){
\r
551 delete this.nodeHash[node.id];
\r
555 toString : function(){
\r
556 return '[Tree'+(this.id?' '+this.id:'')+']';
\r
560 restrictExpand : function(node){
\r
561 var p = node.parentNode;
\r
563 if(p.expandedChild && p.expandedChild.parentNode == p){
\r
564 p.expandedChild.collapse();
\r
566 p.expandedChild = node;
\r
571 * Retrieve an array of checked nodes, or an array of a specific attribute of checked nodes (e.g. 'id')
\r
572 * @param {String} attribute (optional) Defaults to null (return the actual nodes)
\r
573 * @param {TreeNode} startNode (optional) The node to start from, defaults to the root
\r
576 getChecked : function(a, startNode){
\r
577 startNode = startNode || this.root;
\r
579 var f = function(){
\r
580 if(this.attributes.checked){
\r
581 r.push(!a ? this : (a == 'id' ? this.id : this.attributes[a]));
\r
584 startNode.cascade(f);
\r
589 * Returns the default {@link Ext.tree.TreeLoader} for this TreePanel.
\r
590 * @return {Ext.tree.TreeLoader} The TreeLoader for this TreePanel.
\r
592 getLoader : function(){
\r
593 return this.loader;
\r
599 expandAll : function(){
\r
600 this.root.expand(true);
\r
604 * Collapse all nodes
\r
606 collapseAll : function(){
\r
607 this.root.collapse(true);
\r
611 * Returns the selection model used by this TreePanel.
\r
612 * @return {TreeSelectionModel} The selection model used by this TreePanel
\r
614 getSelectionModel : function(){
\r
615 if(!this.selModel){
\r
616 this.selModel = new Ext.tree.DefaultSelectionModel();
\r
618 return this.selModel;
\r
622 * Expands a specified path in this TreePanel. A path can be retrieved from a node with {@link Ext.data.Node#getPath}
\r
623 * @param {String} path
\r
624 * @param {String} attr (optional) The attribute used in the path (see {@link Ext.data.Node#getPath} for more info)
\r
625 * @param {Function} callback (optional) The callback to call when the expand is complete. The callback will be called with
\r
626 * (bSuccess, oLastNode) where bSuccess is if the expand was successful and oLastNode is the last node that was expanded.
\r
628 expandPath : function(path, attr, callback){
\r
629 attr = attr || 'id';
\r
630 var keys = path.split(this.pathSeparator);
\r
631 var curNode = this.root;
\r
632 if(curNode.attributes[attr] != keys[1]){ // invalid root
\r
634 callback(false, null);
\r
639 var f = function(){
\r
640 if(++index == keys.length){
\r
642 callback(true, curNode);
\r
646 var c = curNode.findChild(attr, keys[index]);
\r
649 callback(false, curNode);
\r
654 c.expand(false, false, f);
\r
656 curNode.expand(false, false, f);
\r
660 * Selects the node in this tree at the specified path. A path can be retrieved from a node with {@link Ext.data.Node#getPath}
\r
661 * @param {String} path
\r
662 * @param {String} attr (optional) The attribute used in the path (see {@link Ext.data.Node#getPath} for more info)
\r
663 * @param {Function} callback (optional) The callback to call when the selection is complete. The callback will be called with
\r
664 * (bSuccess, oSelNode) where bSuccess is if the selection was successful and oSelNode is the selected node.
\r
666 selectPath : function(path, attr, callback){
\r
667 attr = attr || 'id';
\r
668 var keys = path.split(this.pathSeparator),
\r
670 if(keys.length > 1){
\r
671 var f = function(success, node){
\r
672 if(success && node){
\r
673 var n = node.findChild(attr, v);
\r
679 }else if(callback){
\r
680 callback(false, n);
\r
684 callback(false, n);
\r
688 this.expandPath(keys.join(this.pathSeparator), attr, f);
\r
690 this.root.select();
\r
692 callback(true, this.root);
\r
698 * Returns the underlying Element for this tree
\r
699 * @return {Ext.Element} The Element
\r
701 getTreeEl : function(){
\r
706 onRender : function(ct, position){
\r
707 Ext.tree.TreePanel.superclass.onRender.call(this, ct, position);
\r
708 this.el.addClass('x-tree');
\r
709 this.innerCt = this.body.createChild({tag:'ul',
\r
710 cls:'x-tree-root-ct ' +
\r
711 (this.useArrows ? 'x-tree-arrows' : this.lines ? 'x-tree-lines' : 'x-tree-no-lines')});
\r
715 initEvents : function(){
\r
716 Ext.tree.TreePanel.superclass.initEvents.call(this);
\r
718 if(this.containerScroll){
\r
719 Ext.dd.ScrollManager.register(this.body);
\r
721 if((this.enableDD || this.enableDrop) && !this.dropZone){
\r
723 * The dropZone used by this tree if drop is enabled (see {@link #enableDD} or {@link #enableDrop})
\r
724 * @property dropZone
\r
725 * @type Ext.tree.TreeDropZone
\r
727 this.dropZone = new Ext.tree.TreeDropZone(this, this.dropConfig || {
\r
728 ddGroup: this.ddGroup || 'TreeDD', appendOnly: this.ddAppendOnly === true
\r
731 if((this.enableDD || this.enableDrag) && !this.dragZone){
\r
733 * The dragZone used by this tree if drag is enabled (see {@link #enableDD} or {@link #enableDrag})
\r
734 * @property dragZone
\r
735 * @type Ext.tree.TreeDragZone
\r
737 this.dragZone = new Ext.tree.TreeDragZone(this, this.dragConfig || {
\r
738 ddGroup: this.ddGroup || 'TreeDD',
\r
739 scroll: this.ddScroll
\r
742 this.getSelectionModel().init(this);
\r
746 afterRender : function(){
\r
747 Ext.tree.TreePanel.superclass.afterRender.call(this);
\r
748 this.root.render();
\r
749 if(!this.rootVisible){
\r
750 this.root.renderChildren();
\r
754 beforeDestroy : function(){
\r
756 Ext.dd.ScrollManager.unregister(this.body);
\r
757 Ext.destroy(this.dropZone, this.dragZone);
\r
759 Ext.destroy(this.root, this.loader);
\r
760 this.nodeHash = this.root = this.loader = null;
\r
761 Ext.tree.TreePanel.superclass.beforeDestroy.call(this);
\r
765 * @cfg {String/Number} activeItem
\r
769 * @cfg {Boolean} autoDestroy
\r
773 * @cfg {Object/String/Function} autoLoad
\r
777 * @cfg {Boolean} autoWidth
\r
781 * @cfg {Boolean/Number} bufferResize
\r
785 * @cfg {String} defaultType
\r
789 * @cfg {Object} defaults
\r
793 * @cfg {Boolean} hideBorders
\r
797 * @cfg {Mixed} items
\r
801 * @cfg {String} layout
\r
805 * @cfg {Object} layoutConfig
\r
809 * @cfg {Boolean} monitorResize
\r
837 * @method findByType
\r
841 * @method getComponent
\r
845 * @method getLayout
\r
849 * @method getUpdater
\r
869 * @method removeAll
\r
873 * @event afterLayout
\r
881 * @event beforeremove
\r
892 * @cfg {String} allowDomMove @hide
\r
895 * @cfg {String} autoEl @hide
\r
898 * @cfg {String} applyTo @hide
\r
901 * @cfg {String} contentEl @hide
\r
904 * @cfg {String} disabledClass @hide
\r
907 * @cfg {String} elements @hide
\r
910 * @cfg {String} html @hide
\r
913 * @cfg {Boolean} preventBodyReset
\r
917 * @property disabled
\r
921 * @method applyToMarkup
\r
933 * @method setDisabled
\r
938 Ext.tree.TreePanel.nodeTypes = {};
\r
940 Ext.reg('treepanel', Ext.tree.TreePanel);