X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/3789b528d8dd8aad4558e38e22d775bcab1cbd36..f562e4c6e5fac7bcb445985b99acbea4d706e6f0:/src/data/TreeStore.js?ds=sidebyside
diff --git a/src/data/TreeStore.js b/src/data/TreeStore.js
index 8329371b..84ed73ec 100644
--- a/src/data/TreeStore.js
+++ b/src/data/TreeStore.js
@@ -1,19 +1,33 @@
+/*
+
+This file is part of Ext JS 4
+
+Copyright (c) 2011 Sencha Inc
+
+Contact: http://www.sencha.com/contact
+
+GNU General Public License Usage
+This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file. Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
+
+If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
+
+*/
/**
- * @class Ext.data.TreeStore
- * @extends Ext.data.AbstractStore
- *
* 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,
+ * The standard Tree fields will also be copied onto the Model for maintaining their state. These fields are listed
+ * in the {@link Ext.data.NodeInterface} documentation.
+ *
+ * # 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'.
*/
@@ -23,14 +37,33 @@ Ext.define('Ext.data.TreeStore', {
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 'node'.
+ * @cfg {String} nodeParam
+ * The name of the parameter sent to the server which contains the identifier of the node.
+ * Defaults to 'node'.
*/
nodeParam: 'node',
@@ -39,7 +72,7 @@ Ext.define('Ext.data.TreeStore', {
* 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.
@@ -47,18 +80,18 @@ Ext.define('Ext.data.TreeStore', {
defaultRootProperty: 'children',
/**
- * @cfg {Boolean} folderSort Set to true to automatically prepend a leaf sorter (defaults to undefined)
+ * @cfg {Boolean} folderSort
+ * Set to true to automatically prepend a leaf sorter. Defaults to `undefined`.
*/
folderSort: false,
-
+
constructor: function(config) {
- var me = this,
+ 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.
@@ -69,160 +102,118 @@ Ext.define('Ext.data.TreeStore', {
}
me.callParent([config]);
-
+
// 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
- * @param {Node} parent The parent node
- * @param {Node} node The newly appended node
- * @param {Number} index The index of the newly appended node
+ * @alias Ext.data.Tree#append
*/
"append",
-
+
/**
* @event remove
- * Fires when a child node is removed from a node in this store's tree.
- * @param {Tree} tree The owner tree
- * @param {Node} parent The parent node
- * @param {Node} node The child node removed
+ * @alias Ext.data.Tree#remove
*/
"remove",
-
+
/**
* @event move
- * Fires when a node is moved to a new location in the store's tree
- * @param {Tree} tree The owner tree
- * @param {Node} node The node moved
- * @param {Node} oldParent The old parent of this node
- * @param {Node} newParent The new parent of this node
- * @param {Number} index The index it was moved to
+ * @alias Ext.data.Tree#move
*/
"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
- * @param {Node} parent The parent node
- * @param {Node} node The child node inserted
- * @param {Node} refNode The child node the node was inserted before
+ * @alias Ext.data.Tree#insert
*/
"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
- * @param {Node} parent The parent node
- * @param {Node} node The child node to be appended
+ * @alias Ext.data.Tree#beforeappend
*/
"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
- * @param {Node} parent The parent node
- * @param {Node} node The child node to be removed
+ * @alias Ext.data.Tree#beforeremove
*/
"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
- * @param {Node} node The node being moved
- * @param {Node} oldParent The parent of the node
- * @param {Node} newParent The new parent the node is moving to
- * @param {Number} index The index it is being moved to
+ * @alias Ext.data.Tree#beforemove
*/
"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
- * @param {Node} parent The parent node
- * @param {Node} node The child node to be inserted
- * @param {Node} refNode The child node the node is being inserted before
+ * @alias Ext.data.Tree#beforeinsert
*/
"beforeinsert",
-
+
/**
* @event expand
- * Fires when this node is expanded.
- * @param {Node} this The expanding node
+ * @alias Ext.data.Tree#expand
*/
"expand",
-
+
/**
* @event collapse
- * Fires when this node is collapsed.
- * @param {Node} this The collapsing node
+ * @alias Ext.data.Tree#collapse
*/
"collapse",
-
+
/**
* @event beforeexpand
- * Fires before this node is expanded.
- * @param {Node} this The expanding node
+ * @alias Ext.data.Tree#beforeexpand
*/
"beforeexpand",
-
+
/**
* @event beforecollapse
- * Fires before this node is collapsed.
- * @param {Node} this The collapsing node
+ * @alias Ext.data.Tree#beforecollapse
*/
"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
+ * @alias Ext.data.Tree#rootchange
*/
"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
- * @param {Node} The new root node.
+ * @event sort
+ * Fires when this TreeStore is sorted.
+ * @param {Ext.data.NodeInterface} node The node that is sorted.
*/
- 'rootchange'
+ 'sort'
);
-
+
//
if (Ext.isDefined(me.nodeParameter)) {
if (Ext.isDefined(Ext.global.console)) {
@@ -233,12 +224,12 @@ Ext.define('Ext.data.TreeStore', {
}
//
},
-
+
// inherit docs
setProxy: function(proxy) {
var reader,
needsRoot;
-
+
if (proxy instanceof Ext.data.proxy.Proxy) {
// proxy instance, check if a root was set
needsRoot = Ext.isEmpty(proxy.getReader().root);
@@ -258,17 +249,17 @@ Ext.define('Ext.data.TreeStore', {
reader.buildExtractors(true);
}
},
-
+
// inherit docs
onBeforeSort: function() {
if (this.folderSort) {
this.sort({
property: 'leaf',
direction: 'ASC'
- }, 'prepend', false);
+ }, 'prepend', false);
}
},
-
+
/**
* Called before a node is expanded.
* @private
@@ -291,10 +282,10 @@ Ext.define('Ext.data.TreeStore', {
callback: function() {
Ext.callback(callback, scope || node, [node.childNodes]);
}
- });
+ });
}
},
-
+
//inherit docs
getNewRecords: function() {
return Ext.Array.filter(this.tree.flatten(), this.filterNew);
@@ -304,7 +295,7 @@ Ext.define('Ext.data.TreeStore', {
getUpdatedRecords: function() {
return Ext.Array.filter(this.tree.flatten(), this.filterUpdated);
},
-
+
/**
* Called before a node is collapsed.
* @private
@@ -315,23 +306,23 @@ Ext.define('Ext.data.TreeStore', {
onBeforeNodeCollapse: function(node, callback, scope) {
callback.call(scope || node, node.childNodes);
},
-
+
onNodeRemove: function(parent, node) {
var removed = this.removed;
-
+
if (!node.isReplace && Ext.Array.indexOf(removed, node) == -1) {
removed.push(node);
}
},
-
+
onNodeAdded: function(parent, node) {
var proxy = this.getProxy(),
reader = proxy.getReader(),
data = node.raw || node.data,
dataRoot, children;
-
- Ext.Array.remove(this.removed, node);
-
+
+ Ext.Array.remove(this.removed, node);
+
if (!node.isLeaf() && !node.isLoaded()) {
dataRoot = reader.getRoot(data);
if (dataRoot) {
@@ -340,18 +331,18 @@ 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) {
var me = this;
- root = root || {};
+ root = root || {};
if (!root.isNode) {
- // create a default rootNode and create internal data struct.
+ // create a default rootNode and create internal data struct.
Ext.applyIf(root, {
id: me.defaultRootId,
text: 'Root',
@@ -364,20 +355,20 @@ Ext.define('Ext.data.TreeStore', {
// Because we have decorated the model with new fields,
// we need to build new extactor functions on the reader.
me.getProxy().getReader().buildExtractors(true);
-
+
// When we add the root to the tree, it will automaticaly get the NodeInterface
me.tree.setRootNode(root);
-
+
// If the user has set expanded: true on the root, we want to call the expand function
- if (!root.isLoaded() && root.isExpanded()) {
+ if (!root.isLoaded() && (me.autoLoad === true || root.isExpanded())) {
me.load({
node: root
});
}
-
+
return root;
},
-
+
/**
* Returns the root node for this tree.
* @return {Ext.data.NodeInterface}
@@ -396,7 +387,7 @@ Ext.define('Ext.data.TreeStore', {
/**
* Loads the Store using its configured {@link #proxy}.
- * @param {Object} options Optional config object. This is passed into the {@link Ext.data.Operation Operation}
+ * @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.
* The options can also contain a node, which indicates which node is to be loaded. If not specified, it will
* default to the root node.
@@ -404,11 +395,11 @@ Ext.define('Ext.data.TreeStore', {
load: function(options) {
options = options || {};
options.params = options.params || {};
-
+
var me = this,
node = options.node || me.tree.getRootNode(),
root;
-
+
// If there is not a node it means the user hasnt defined a rootnode yet. In this case lets just
// create one for them.
if (!node) {
@@ -416,29 +407,29 @@ Ext.define('Ext.data.TreeStore', {
expanded: true
});
}
-
+
if (me.clearOnLoad) {
- node.removeAll();
+ node.removeAll(true);
}
-
+
Ext.applyIf(options, {
node: node
});
options.params[me.nodeParam] = node ? node.getId() : 'root';
-
+
if (node) {
node.set('loading', true);
}
-
+
return me.callParent([options]);
},
-
+
/**
* Fills a node with a series of child records.
* @private
* @param {Ext.data.NodeInterface} node The node to fill
- * @param {Array} records The records to add
+ * @param {Ext.data.Model[]} records The records to add
*/
fillNode: function(node, records) {
var me = this,
@@ -451,12 +442,12 @@ Ext.define('Ext.data.TreeStore', {
sortCollection.sort(me.sorters.items);
records = sortCollection.items;
}
-
+
node.set('loaded', true);
for (; i < ln; i++) {
node.appendChild(records[i], undefined, true);
}
-
+
return records;
},
@@ -467,21 +458,32 @@ Ext.define('Ext.data.TreeStore', {
records = operation.getRecords(),
node = operation.node;
+ me.loading = false;
node.set('loading', false);
if (successful) {
records = me.fillNode(node, records);
}
+ // The load event has an extra node parameter
+ // (differing from the load event described in AbstractStore)
+ /**
+ * @event load
+ * Fires whenever the store reads data from a remote data source.
+ * @param {Ext.data.TreeStore} this
+ * @param {Ext.data.NodeInterface} node The node that was loaded.
+ * @param {Ext.data.Model[]} records An array of records.
+ * @param {Boolean} successful True if the operation was successful.
+ */
// deprecate read?
me.fireEvent('read', me, operation.node, records, successful);
me.fireEvent('load', me, operation.node, records, successful);
//this is a callback that would have been passed to the 'read' function and is optional
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.Model[]} records The array of new records
* @param {Ext.data.Operation} operation The operation that just completed
* @param {Boolean} success True if the operation was successful
*/
@@ -518,9 +520,9 @@ 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.Model[]} records The array of updated records
* @param {Ext.data.Operation} operation The operation that just completed
* @param {Boolean} success True if the operation was successful
*/
@@ -549,9 +551,9 @@ 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.Model[]} records The array of removed records
* @param {Ext.data.Operation} operation The operation that just completed
* @param {Boolean} success True if the operation was successful
*/
@@ -576,7 +578,8 @@ Ext.define('Ext.data.TreeStore', {
} else {
me.tree.sort(sorterFn, true);
me.fireEvent('datachanged', me);
- }
+ }
me.fireEvent('sort', me);
}
-});
\ No newline at end of file
+});
+