Insert node(s) as the last child node of this node.
- *If the node was previously a child node of another parent node, it will be removed from that node first.
- * @param {Node/Array} node The node or Array of nodes to append - * @return {Node} The appended node if single append, or null if an array was passed + * Inserts node(s) as the last child node of this node. + * + * If the node was previously a child node of another parent node, it will be removed from that node first. + * + * @param {Ext.data.NodeInterface/Ext.data.NodeInterface[]} node The node or Array of nodes to append + * @return {Ext.data.NodeInterface} The appended node if single append, or null if an array was passed */ appendChild : function(node, suppressEvents, suppressNodeUpdate) { var me = this, @@ -364,9 +516,9 @@ Ext.define('Ext.data.NodeInterface', { } else { // Make sure it is a record node = me.createNode(node); - + if (suppressEvents !== true && me.fireEvent("beforeappend", me, node) === false) { - return false; + return false; } index = me.childNodes.length; @@ -390,7 +542,7 @@ Ext.define('Ext.data.NodeInterface', { node.nextSibling = null; me.setLastChild(node); - + ps = me.childNodes[index - 1]; if (ps) { node.previousSibling = ps; @@ -401,28 +553,28 @@ Ext.define('Ext.data.NodeInterface', { } node.updateInfo(suppressNodeUpdate); - + // As soon as we append a child to this node, we are loaded if (!me.isLoaded()) { - me.set('loaded', true); + me.set('loaded', true); } // If this node didnt have any childnodes before, update myself else if (me.childNodes.length === 1) { me.set('loaded', me.isLoaded()); } - + if (suppressEvents !== true) { me.fireEvent("append", me, node, index); if (oldParent) { node.fireEvent("move", node, oldParent, me, index); - } + } } return node; } }, - + /** * Returns the bubble target for this node * @private @@ -434,14 +586,14 @@ Ext.define('Ext.data.NodeInterface', { /** * Removes a child node from this node. - * @param {Node} node The node to remove - * @param {Boolean} destroy true to destroy the node upon removal. Defaults to false. - * @return {Node} The removed node + * @param {Ext.data.NodeInterface} node The node to remove + * @param {Boolean} [destroy=false] True to destroy the node upon removal. + * @return {Ext.data.NodeInterface} The removed node */ removeChild : function(node, destroy, suppressEvents, suppressNodeUpdate) { var me = this, index = me.indexOf(node); - + if (index == -1 || (suppressEvents !== true && me.fireEvent("beforeremove", me, node) === false)) { return false; } @@ -456,7 +608,7 @@ Ext.define('Ext.data.NodeInterface', { if (me.lastChild == node) { me.setLastChild(node.previousSibling); } - + // update siblings if (node.previousSibling) { node.previousSibling.nextSibling = node.nextSibling; @@ -470,13 +622,13 @@ Ext.define('Ext.data.NodeInterface', { if (suppressEvents !== true) { me.fireEvent("remove", me, node); } - - + + // If this node suddenly doesnt have childnodes anymore, update myself if (!me.childNodes.length) { me.set('loaded', me.isLoaded()); } - + if (destroy) { node.destroy(true); } else { @@ -488,10 +640,10 @@ Ext.define('Ext.data.NodeInterface', { /** * Creates a copy (clone) of this Node. - * @param {String} id (optional) A new id, defaults to this Node's id. See{@link #id}.
- * @param {Boolean} deep (optional) If passed as true, all child Nodes are recursively copied into the new Node.
If omitted or false, the copy will have no child Nodes.
- * @return {Node} A copy of this Node. + * @param {String} [id] A new id, defaults to this Node's id. + * @param {Boolean} [deep=false] True to recursively copy all child Nodes into the new Node. + * False to copy without child Nodes. + * @return {Ext.data.NodeInterface} A copy of this Node. */ copy: function(newId, deep) { var me = this, @@ -509,13 +661,13 @@ Ext.define('Ext.data.NodeInterface', { }, /** - * Clear the node. + * Clears the node. * @private - * @param {Boolean} destroy True to destroy the node. + * @param {Boolean} [destroy=false] True to destroy the node. */ clear : function(destroy) { var me = this; - + // clear any references from the node me.parentNode = me.previousSibling = me.nextSibling = null; if (destroy) { @@ -535,7 +687,7 @@ Ext.define('Ext.data.NodeInterface', { */ var me = this, options = me.destroyOptions; - + if (silent === true) { me.clear(true); Ext.each(me.childNodes, function(n) { @@ -553,9 +705,9 @@ Ext.define('Ext.data.NodeInterface', { /** * Inserts the first node before the second node in this nodes childNodes collection. - * @param {Node} node The node to insert - * @param {Node} refNode The node to insert before (if null the node is appended) - * @return {Node} The inserted node + * @param {Ext.data.NodeInterface} node The node to insert + * @param {Ext.data.NodeInterface} refNode The node to insert before (if null the node is appended) + * @return {Ext.data.NodeInterface} The inserted node */ insertBefore : function(node, refNode, suppressEvents) { var me = this, @@ -563,11 +715,11 @@ Ext.define('Ext.data.NodeInterface', { oldParent = node.parentNode, refIndex = index, ps; - + if (!refNode) { // like standard Dom, refNode can be null for append return me.appendChild(node); } - + // nothing to do if (node == refNode) { return false; @@ -575,11 +727,11 @@ Ext.define('Ext.data.NodeInterface', { // Make sure it is a record with the NodeInterface node = me.createNode(node); - + if (suppressEvents !== true && me.fireEvent("beforeinsert", me, node, refNode) === false) { return false; } - + // when moving internally, indexes will change after remove if (oldParent == me && me.indexOf(node) < index) { refIndex--; @@ -599,10 +751,10 @@ Ext.define('Ext.data.NodeInterface', { Ext.Array.splice(me.childNodes, refIndex, 0, node); node.parentNode = me; - + node.nextSibling = refNode; refNode.previousSibling = node; - + ps = me.childNodes[refIndex - 1]; if (ps) { node.previousSibling = ps; @@ -611,12 +763,12 @@ Ext.define('Ext.data.NodeInterface', { } else { node.previousSibling = null; } - + node.updateInfo(); - + if (!me.isLoaded()) { - me.set('loaded', true); - } + me.set('loaded', true); + } // If this node didnt have any childnodes before, update myself else if (me.childNodes.length === 1) { me.set('loaded', me.isLoaded()); @@ -627,18 +779,18 @@ Ext.define('Ext.data.NodeInterface', { if (oldParent) { node.fireEvent("move", node, oldParent, me, refIndex, refNode); - } + } } return node; }, - + /** * Insert a node into this node * @param {Number} index The zero-based index to insert the node at * @param {Ext.data.Model} node The node to insert - * @return {Ext.data.Record} The record you just inserted - */ + * @return {Ext.data.Model} The record you just inserted + */ insertChild: function(index, node) { var sibling = this.childNodes[index]; if (sibling) { @@ -651,8 +803,8 @@ Ext.define('Ext.data.NodeInterface', { /** * Removes this node from its parent - * @param {Boolean} destroy true to destroy the node upon removal. Defaults to false. - * @return {Node} this + * @param {Boolean} [destroy=false] True to destroy the node upon removal. + * @return {Ext.data.NodeInterface} this */ remove : function(destroy, suppressEvents) { var parentNode = this.parentNode; @@ -665,8 +817,8 @@ Ext.define('Ext.data.NodeInterface', { /** * Removes all child nodes from this node. - * @param {Boolean} destroy true to destroy the node upon removal. Defaults to false. - * @return {Node} this + * @param {Boolean} [destroy=false]this reference) in which the function is executed. Defaults to the current Node.
- * @param {Array} args (optional) The args to call the function with (default to passing the current Node)
+ * @param {Object} [scope] The scope (this reference) in which the function is executed. Defaults to the current Node.
+ * @param {Array} [args] The args to call the function with. Defaults to passing the current Node.
*/
cascadeBy : function(fn, scope, args) {
if (fn.apply(scope || this, args || [this]) !== false) {
@@ -770,8 +942,8 @@ Ext.define('Ext.data.NodeInterface', {
* will be the args provided or the current node. If the function returns false at any point,
* the iteration stops.
* @param {Function} fn The function to call
- * @param {Object} scope (optional) The scope (this reference) in which the function is executed. Defaults to the current Node in the iteration.
- * @param {Array} args (optional) The args to call the function with (default to passing the current Node)
+ * @param {Object} [scope] The scope (this reference) in which the function is executed. Defaults to the current Node in iteration.
+ * @param {Array} [args] The args to call the function with. Defaults to passing the current Node.
*/
eachChild : function(fn, scope, args) {
var childNodes = this.childNodes,
@@ -788,9 +960,9 @@ Ext.define('Ext.data.NodeInterface', {
/**
* Finds the first child that has the attribute with the specified value.
* @param {String} attribute The attribute name
- * @param {Mixed} value The value to search for
- * @param {Boolean} deep (Optional) True to search through nodes deeper than the immediate children
- * @return {Node} The found child or null if none was found
+ * @param {Object} value The value to search for
+ * @param {Boolean} [deep=false] True to search through nodes deeper than the immediate children
+ * @return {Ext.data.NodeInterface} The found child or null if none was found
*/
findChild : function(attribute, value, deep) {
return this.findChildBy(function() {
@@ -799,11 +971,11 @@ Ext.define('Ext.data.NodeInterface', {
},
/**
- * Finds the first child by a custom function. The child matches if the function passed returns true.
- * @param {Function} fn A function which must return true if the passed Node is the required Node.
- * @param {Object} scope (optional) The scope (this reference) in which the function is executed. Defaults to the Node being tested.
- * @param {Boolean} deep (Optional) True to search through nodes deeper than the immediate children
- * @return {Node} The found child or null if none was found
+ * Finds the first child by a custom function. The child matches if the function passed returns true.
+ * @param {Function} fn A function which must return true if the passed Node is the required Node.
+ * @param {Object} [scope] The scope (this reference) in which the function is executed. Defaults to the Node being tested.
+ * @param {Boolean} [deep=false] True to search through nodes deeper than the immediate children
+ * @return {Ext.data.NodeInterface} The found child or null if none was found
*/
findChildBy : function(fn, scope, deep) {
var cs = this.childNodes,
@@ -828,7 +1000,7 @@ Ext.define('Ext.data.NodeInterface', {
/**
* Returns true if this node is an ancestor (at any point) of the passed node.
- * @param {Node} node
+ * @param {Ext.data.NodeInterface} node
* @return {Boolean}
*/
contains : function(node) {
@@ -837,7 +1009,7 @@ Ext.define('Ext.data.NodeInterface', {
/**
* Returns true if the passed node is an ancestor (at any point) of this node.
- * @param {Node} node
+ * @param {Ext.data.NodeInterface} node
* @return {Boolean}
*/
isAncestor : function(node) {
@@ -854,21 +1026,21 @@ Ext.define('Ext.data.NodeInterface', {
/**
* Sorts this nodes children using the supplied sort function.
* @param {Function} fn A function which, when passed two Nodes, returns -1, 0 or 1 depending upon required sort order.
- * @param {Boolean} recursive Whether or not to apply this sort recursively
- * @param {Boolean} suppressEvent Set to true to not fire a sort event.
+ * @param {Boolean} [recursive=false] True to apply this sort recursively
+ * @param {Boolean} [suppressEvent=false] True to not fire a sort event.
*/
sort : function(sortFn, recursive, suppressEvent) {
var cs = this.childNodes,
ln = cs.length,
i, n;
-
+
if (ln > 0) {
Ext.Array.sort(cs, sortFn);
for (i = 0; i < ln; i++) {
n = cs[i];
n.previousSibling = cs[i-1];
n.nextSibling = cs[i+1];
-
+
if (i === 0) {
this.setFirstChild(n);
n.updateInfo();
@@ -881,25 +1053,25 @@ Ext.define('Ext.data.NodeInterface', {
n.sort(sortFn, true, true);
}
}
-
+
if (suppressEvent !== true) {
this.fireEvent('sort', this, cs);
}
}
},
-
+
/**
* Returns true if this node is expaned
* @return {Boolean}
- */
+ */
isExpanded: function() {
return this.get('expanded');
},
-
+
/**
* Returns true if this node is loaded
* @return {Boolean}
- */
+ */
isLoaded: function() {
return this.get('loaded');
},
@@ -907,23 +1079,23 @@ Ext.define('Ext.data.NodeInterface', {
/**
* Returns true if this node is loading
* @return {Boolean}
- */
+ */
isLoading: function() {
return this.get('loading');
},
-
+
/**
* Returns true if this node is the root node
* @return {Boolean}
- */
+ */
isRoot: function() {
return !this.parentNode;
},
-
+
/**
* Returns true if this node is visible
* @return {Boolean}
- */
+ */
isVisible: function() {
var parent = this.parentNode;
while (parent) {
@@ -934,12 +1106,12 @@ Ext.define('Ext.data.NodeInterface', {
}
return true;
},
-
+
/**
* Expand this node.
- * @param {Function} recursive (Optional) True to recursively expand all the children
- * @param {Function} callback (Optional) The function to execute once the expand completes
- * @param {Object} scope (Optional) The scope to run the callback in
+ * @param {Boolean} [recursive=false] True to recursively expand all the children
+ * @param {Function} [callback] The function to execute once the expand completes
+ * @param {Object} [scope] The scope to run the callback in
*/
expand: function(recursive, callback, scope) {
var me = this;
@@ -949,48 +1121,47 @@ Ext.define('Ext.data.NodeInterface', {
// First we start by checking if this node is a parent
if (!me.isLeaf()) {
- // Now we check if this record is already expanding or expanded
- if (!me.isLoading() && !me.isExpanded()) {
- // The TreeStore actually listens for the beforeexpand method and checks
- // whether we have to asynchronously load the children from the server
- // first. Thats why we pass a callback function to the event that the
- // store can call once it has loaded and parsed all the children.
- me.fireEvent('beforeexpand', me, function() {
- me.set('expanded', true);
- me.fireEvent('expand', me, me.childNodes, false);
-
- // Call the expandChildren method if recursive was set to true
- if (recursive) {
- me.expandChildren(true, callback, scope);
- }
- else {
- Ext.callback(callback, scope || me, [me.childNodes]);
- }
- }, me);
- }
- // If it is is already expanded but we want to recursively expand then call expandChildren
- else if (recursive) {
- me.expandChildren(true, callback, scope);
- }
- else {
- Ext.callback(callback, scope || me, [me.childNodes]);
+ // If it's loaded, wait until it loads before proceeding
+ if (me.isLoading()) {
+ me.on('expand', function(){
+ me.expand(recursive, callback, scope);
+ }, me, {single: true});
+ } else {
+ // Now we check if this record is already expanding or expanded
+ if (!me.isExpanded()) {
+ // The TreeStore actually listens for the beforeexpand method and checks
+ // whether we have to asynchronously load the children from the server
+ // first. Thats why we pass a callback function to the event that the
+ // store can call once it has loaded and parsed all the children.
+ me.fireEvent('beforeexpand', me, function(){
+ me.set('expanded', true);
+ me.fireEvent('expand', me, me.childNodes, false);
+
+ // Call the expandChildren method if recursive was set to true
+ if (recursive) {
+ me.expandChildren(true, callback, scope);
+ } else {
+ Ext.callback(callback, scope || me, [me.childNodes]);
+ }
+ }, me);
+ } else if (recursive) {
+ // If it is is already expanded but we want to recursively expand then call expandChildren
+ me.expandChildren(true, callback, scope);
+ } else {
+ Ext.callback(callback, scope || me, [me.childNodes]);
+ }
}
-
- // TODO - if the node isLoading, we probably need to defer the
- // callback until it is loaded (e.g., selectPath would need us
- // to not make the callback until the childNodes exist).
- }
- // If it's not then we fire the callback right away
- else {
+ } else {
+ // If it's not then we fire the callback right away
Ext.callback(callback, scope || me); // leaf = no childNodes
}
},
-
+
/**
* Expand all the children of this node.
- * @param {Function} recursive (Optional) True to recursively expand all the children
- * @param {Function} callback (Optional) The function to execute once all the children are expanded
- * @param {Object} scope (Optional) The scope to run the callback in
+ * @param {Boolean} [recursive=false] True to recursively expand all the children
+ * @param {Function} [callback] The function to execute once all the children are expanded
+ * @param {Object} [scope] The scope to run the callback in
*/
expandChildren: function(recursive, callback, scope) {
var me = this,
@@ -1007,21 +1178,21 @@ Ext.define('Ext.data.NodeInterface', {
nodes[i].expand(recursive, function () {
expanding--;
if (callback && !expanding) {
- Ext.callback(callback, scope || me, [me.childNodes]);
+ Ext.callback(callback, scope || me, [me.childNodes]);
}
- });
+ });
}
}
-
+
if (!expanding && callback) {
Ext.callback(callback, scope || me, [me.childNodes]); }
},
/**
* Collapse this node.
- * @param {Function} recursive (Optional) True to recursively collapse all the children
- * @param {Function} callback (Optional) The function to execute once the collapse completes
- * @param {Object} scope (Optional) The scope to run the callback in
+ * @param {Boolean} [recursive=false] True to recursively collapse all the children
+ * @param {Function} [callback] The function to execute once the collapse completes
+ * @param {Object} [scope] The scope to run the callback in
*/
collapse: function(recursive, callback, scope) {
var me = this;
@@ -1031,17 +1202,17 @@ Ext.define('Ext.data.NodeInterface', {
// Now we check if this record is already collapsing or collapsed
if (!me.collapsing && me.isExpanded()) {
me.fireEvent('beforecollapse', me, function() {
- me.set('expanded', false);
+ me.set('expanded', false);
me.fireEvent('collapse', me, me.childNodes, false);
-
- // Call the collapseChildren method if recursive was set to true
+
+ // Call the collapseChildren method if recursive was set to true
if (recursive) {
me.collapseChildren(true, callback, scope);
}
else {
- Ext.callback(callback, scope || me, [me.childNodes]);
+ Ext.callback(callback, scope || me, [me.childNodes]);
}
- }, me);
+ }, me);
}
// If it is is already collapsed but we want to recursively collapse then call collapseChildren
else if (recursive) {
@@ -1050,15 +1221,15 @@ Ext.define('Ext.data.NodeInterface', {
}
// If it's not then we fire the callback right away
else {
- Ext.callback(callback, scope || me, [me.childNodes]);
+ Ext.callback(callback, scope || me, [me.childNodes]);
}
},
-
+
/**
* Collapse all the children of this node.
- * @param {Function} recursive (Optional) True to recursively collapse all the children
- * @param {Function} callback (Optional) The function to execute once all the children are collapsed
- * @param {Object} scope (Optional) The scope to run the callback in
+ * @param {Function} [recursive=false] True to recursively collapse all the children
+ * @param {Function} [callback] The function to execute once all the children are collapsed
+ * @param {Object} [scope] The scope to run the callback in
*/
collapseChildren: function(recursive, callback, scope) {
var me = this,
@@ -1075,12 +1246,12 @@ Ext.define('Ext.data.NodeInterface', {
nodes[i].collapse(recursive, function () {
collapsing--;
if (callback && !collapsing) {
- Ext.callback(callback, scope || me, [me.childNodes]);
+ Ext.callback(callback, scope || me, [me.childNodes]);
}
- });
+ });
}
}
-
+
if (!collapsing && callback) {
Ext.callback(callback, scope || me, [me.childNodes]);
}