/**
- * @class Ext.data.TreeStore
- * @extends Ext.data.AbstractStore
- *
- * The TreeStore is a store implementation that is backed by by an {@link Ext.data.Tree}.
+
+
+
+
+ The source code
+
+
+
+
+
+
+
/**
+ * The TreeStore is a store implementation that is backed by by an {@link Ext.data.Tree}.
* It provides convenience methods for loading nodes, as well as the ability to use
* the hierarchical tree structure combined with a store. This class is generally used
* in conjunction with {@link Ext.tree.Panel}. This class also relays many events from
* the Tree for convenience.
*
- * ## Using Models
+ * # Using Models
+ *
* If no Model is specified, an implicit model will be created that implements {@link Ext.data.NodeInterface}.
* The standard Tree fields will also be copied onto the Model for maintaining their state.
*
- * ## Reading Nested Data
- * For the tree to read nested data, the {@link Ext.data.Reader} must be configured with a root property,
+ * # Reading Nested Data
+ *
+ * For the tree to read nested data, the {@link Ext.data.reader.Reader} must be configured with a root property,
* so the reader can find nested data for each node. If a root is not specified, it will default to
* 'children'.
*/
@@ -22,32 +38,52 @@ Ext.define('Ext.data.TreeStore', {
alias: 'store.tree',
requires: ['Ext.data.Tree', 'Ext.data.NodeInterface', 'Ext.data.NodeStore'],
- /**
- * @cfg {Boolean} clearOnLoad (optional) Default to true. Remove previously existing
- * child nodes before loading.
+ /**
+ * @cfg {Ext.data.Model/Ext.data.NodeInterface/Object} root
+ * The root node for this store. For example:
+ *
+ * root: {
+ * expanded: true,
+ * text: "My Root",
+ * children: [
+ * { text: "Child 1", leaf: true },
+ * { text: "Child 2", expanded: true, children: [
+ * { text: "GrandChild", leaf: true }
+ * ] }
+ * ]
+ * }
+ *
+ * Setting the `root` config option is the same as calling {@link #setRootNode}.
+ */
+
+ /**
+ * @cfg {Boolean} clearOnLoad
+ * Remove previously existing child nodes before loading. Default to true.
*/
clearOnLoad : true,
- /**
- * @cfg {String} nodeParam The name of the parameter sent to the server which contains
- * the identifier of the node. Defaults to <tt>'node'</tt>.
+ /**
+ * @cfg {String} nodeParam
+ * The name of the parameter sent to the server which contains the identifier of the node.
+ * Defaults to 'node'.
*/
nodeParam: 'node',
- /**
+ /**
* @cfg {String} defaultRootId
* The default root id. Defaults to 'root'
*/
defaultRootId: 'root',
- /**
+ /**
* @cfg {String} defaultRootProperty
* The root property to specify on the reader if one is not explicitly defined.
*/
defaultRootProperty: 'children',
- /**
- * @cfg {Boolean} folderSort Set to true to automatically prepend a leaf sorter (defaults to <tt>undefined</tt>)
+ /**
+ * @cfg {Boolean} folderSort
+ * Set to true to automatically prepend a leaf sorter. Defaults to `undefined`.
*/
folderSort: false,
@@ -55,11 +91,10 @@ Ext.define('Ext.data.TreeStore', {
var me = this,
root,
fields;
-
config = Ext.apply({}, config);
- /**
+ /**
* If we have no fields declare for the store, add some defaults.
* These will be ignored if a model is explicitly specified.
*/
@@ -72,26 +107,9 @@ Ext.define('Ext.data.TreeStore', {
// We create our data tree.
me.tree = Ext.create('Ext.data.Tree');
-
- me.tree.on({
- scope: me,
- remove: me.onNodeRemove,
- beforeexpand: me.onBeforeNodeExpand,
- beforecollapse: me.onBeforeNodeCollapse,
- append: me.onNodeAdded,
- insert: me.onNodeAdded
- });
-
- me.onBeforeSort();
-
- root = me.root;
- if (root) {
- delete me.root;
- me.setRootNode(root);
- }
me.relayEvents(me.tree, [
- /**
+ /**
* @event append
* Fires when a new child node is appended to a node in this store's tree.
* @param {Tree} tree The owner tree
@@ -101,7 +119,7 @@ Ext.define('Ext.data.TreeStore', {
*/
"append",
- /**
+ /**
* @event remove
* Fires when a child node is removed from a node in this store's tree.
* @param {Tree} tree The owner tree
@@ -110,7 +128,7 @@ Ext.define('Ext.data.TreeStore', {
*/
"remove",
- /**
+ /**
* @event move
* Fires when a node is moved to a new location in the store's tree
* @param {Tree} tree The owner tree
@@ -121,7 +139,7 @@ Ext.define('Ext.data.TreeStore', {
*/
"move",
- /**
+ /**
* @event insert
* Fires when a new child node is inserted in a node in this store's tree.
* @param {Tree} tree The owner tree
@@ -131,7 +149,7 @@ Ext.define('Ext.data.TreeStore', {
*/
"insert",
- /**
+ /**
* @event beforeappend
* Fires before a new child is appended to a node in this store's tree, return false to cancel the append.
* @param {Tree} tree The owner tree
@@ -140,7 +158,7 @@ Ext.define('Ext.data.TreeStore', {
*/
"beforeappend",
- /**
+ /**
* @event beforeremove
* Fires before a child is removed from a node in this store's tree, return false to cancel the remove.
* @param {Tree} tree The owner tree
@@ -149,7 +167,7 @@ Ext.define('Ext.data.TreeStore', {
*/
"beforeremove",
- /**
+ /**
* @event beforemove
* Fires before a node is moved to a new location in the store's tree. Return false to cancel the move.
* @param {Tree} tree The owner tree
@@ -160,7 +178,7 @@ Ext.define('Ext.data.TreeStore', {
*/
"beforemove",
- /**
+ /**
* @event beforeinsert
* Fires before a new child is inserted in a node in this store's tree, return false to cancel the insert.
* @param {Tree} tree The owner tree
@@ -170,51 +188,70 @@ Ext.define('Ext.data.TreeStore', {
*/
"beforeinsert",
- /**
+ /**
* @event expand
* Fires when this node is expanded.
* @param {Node} this The expanding node
*/
"expand",
- /**
+ /**
* @event collapse
* Fires when this node is collapsed.
* @param {Node} this The collapsing node
*/
"collapse",
- /**
+ /**
* @event beforeexpand
* Fires before this node is expanded.
* @param {Node} this The expanding node
*/
"beforeexpand",
- /**
+ /**
* @event beforecollapse
* Fires before this node is collapsed.
* @param {Node} this The collapsing node
*/
"beforecollapse",
- /**
+ /**
* @event sort
* Fires when this TreeStore is sorted.
* @param {Node} node The node that is sorted.
*/
"sort",
- /**
+ /**
* @event rootchange
* Fires whenever the root node is changed in the tree.
* @param {Ext.data.Model} root The new root
*/
"rootchange"
]);
+
+ me.tree.on({
+ scope: me,
+ remove: me.onNodeRemove,
+ // this event must follow the relay to beforeitemexpand to allow users to
+ // cancel the expand:
+ beforeexpand: me.onBeforeNodeExpand,
+ beforecollapse: me.onBeforeNodeCollapse,
+ append: me.onNodeAdded,
+ insert: me.onNodeAdded
+ });
+
+ me.onBeforeSort();
+
+ root = me.root;
+ if (root) {
+ delete me.root;
+ me.setRootNode(root);
+ }
me.addEvents(
- /**
+ /**
* @event rootchange
* Fires when the root node on this TreeStore is changed.
* @param {Ext.data.TreeStore} store This TreeStore
@@ -269,7 +306,7 @@ Ext.define('Ext.data.TreeStore', {
}
},
- /**
+ /**
* Called before a node is expanded.
* @private
* @param {Ext.data.NodeInterface} node The node being expanded.
@@ -305,7 +342,7 @@ Ext.define('Ext.data.TreeStore', {
return Ext.Array.filter(this.tree.flatten(), this.filterUpdated);
},
- /**
+ /**
* Called before a node is collapsed.
* @private
* @param {Ext.data.NodeInterface} node The node being collapsed.
@@ -341,9 +378,9 @@ Ext.define('Ext.data.TreeStore', {
}
},
- /**
- * Sets the root node for this store
- * @param {Ext.data.Model/Ext.data.NodeInterface} root
+ /**
+ * Sets the root node for this store. See also the {@link #root} config option.
+ * @param {Ext.data.Model/Ext.data.NodeInterface/Object} root
* @return {Ext.data.NodeInterface} The new root
*/
setRootNode: function(root) {
@@ -378,7 +415,7 @@ Ext.define('Ext.data.TreeStore', {
return root;
},
- /**
+ /**
* Returns the root node for this tree.
* @return {Ext.data.NodeInterface}
*/
@@ -386,7 +423,7 @@ Ext.define('Ext.data.TreeStore', {
return this.tree.getRootNode();
},
- /**
+ /**
* Returns the record node by id
* @return {Ext.data.NodeInterface}
*/
@@ -394,7 +431,7 @@ Ext.define('Ext.data.TreeStore', {
return this.tree.getNodeById(id);
},
- /**
+ /**
* Loads the Store using its configured {@link #proxy}.
* @param {Object} options Optional config object. This is passed into the {@link Ext.data.Operation Operation}
* object that is created and then sent to the proxy's {@link Ext.data.proxy.Proxy#read} function.
@@ -434,7 +471,7 @@ Ext.define('Ext.data.TreeStore', {
},
- /**
+ /**
* Fills a node with a series of child records.
* @private
* @param {Ext.data.NodeInterface} node The node to fill
@@ -478,8 +515,8 @@ Ext.define('Ext.data.TreeStore', {
Ext.callback(operation.callback, operation.scope || me, [records, operation, successful]);
},
- /**
- * Create any new records when a write is returned from the server.
+ /**
+ * Creates any new records when a write is returned from the server.
* @private
* @param {Array} records The array of new records
* @param {Ext.data.Operation} operation The operation that just completed
@@ -495,8 +532,8 @@ Ext.define('Ext.data.TreeStore', {
original,
index;
- /**
- * Loop over each record returned from the server. Assume they are
+ /*
+ * Loop over each record returned from the server. Assume they are
* returned in order of how they were sent. If we find a matching
* record, replace it with the newly created one.
*/
@@ -517,8 +554,8 @@ Ext.define('Ext.data.TreeStore', {
}
},
- /**
- * Update any records when a write is returned from the server.
+ /**
+ * Updates any records when a write is returned from the server.
* @private
* @param {Array} records The array of updated records
* @param {Ext.data.Operation} operation The operation that just completed
@@ -548,8 +585,8 @@ Ext.define('Ext.data.TreeStore', {
}
},
- /**
- * Remove any records when a write is returned from the server.
+ /**
+ * Removes any records when a write is returned from the server.
* @private
* @param {Array} records The array of removed records
* @param {Ext.data.Operation} operation The operation that just completed
@@ -563,7 +600,7 @@ Ext.define('Ext.data.TreeStore', {
// inherit docs
removeAll: function() {
- this.getRootNode().destroy();
+ this.getRootNode().destroy(true);
this.fireEvent('clear', this);
},
@@ -579,4 +616,6 @@ Ext.define('Ext.data.TreeStore', {
}
me.fireEvent('sort', me);
}
-});