/**
- * @class Ext.util.Sortable
-
-A mixin which allows a data component to be sorted. This is used by e.g. {@link Ext.data.Store} and {@link Ext.data.TreeStore}.
-
-**NOTE**: This mixin is mainly for internal library use and most users should not need to use it directly. It
-is more likely you will want to use one of the component classes that import this mixin, such as
-{@link Ext.data.Store} or {@link Ext.data.TreeStore}.
- * @markdown
- * @docauthor Tommy Maintz <tommy@sencha.com>
+ * @docauthor Tommy Maintz <tommy@sencha.com>
+ *
+ * A mixin which allows a data component to be sorted. This is used by e.g. {@link Ext.data.Store} and {@link Ext.data.TreeStore}.
+ *
+ * **NOTE**: This mixin is mainly for internal use and most users should not need to use it directly. It
+ * is more likely you will want to use one of the component classes that import this mixin, such as
+ * {@link Ext.data.Store} or {@link Ext.data.TreeStore}.
*/
Ext.define("Ext.util.Sortable", {
/**
- * @property isSortable
- * @type Boolean
+ * @property {Boolean} isSortable
* Flag denoting that this object is sortable. Always true.
*/
isSortable: true,
-
+
/**
- * The default sort direction to use if one is not specified (defaults to "ASC")
- * @property defaultSortDirection
- * @type String
+ * @property {String} defaultSortDirection
+ * The default sort direction to use if one is not specified.
*/
defaultSortDirection: "ASC",
-
+
requires: [
'Ext.util.Sorter'
],
- /**
- * The property in each item that contains the data to sort.
- * @type String
- */
-
+ /**
+ * @property {String} sortRoot
+ * The property in each item that contains the data to sort.
+ */
+
/**
- * Performs initialization of this mixin. Component classes using this mixin should call this method
- * during their own initialization.
+ * Performs initialization of this mixin. Component classes using this mixin should call this method during their
+ * own initialization.
*/
initSortable: function() {
var me = this,
sorters = me.sorters;
-
+
/**
- * The collection of {@link Ext.util.Sorter Sorters} currently applied to this Store
- * @property sorters
- * @type Ext.util.MixedCollection
+ * @property {Ext.util.MixedCollection} sorters
+ * The collection of {@link Ext.util.Sorter Sorters} currently applied to this Store
*/
me.sorters = Ext.create('Ext.util.AbstractMixedCollection', false, function(item) {
return item.id || item.property;
});
-
+
if (sorters) {
me.sorters.addAll(me.decodeSorters(sorters));
}
},
/**
- * <p>Sorts the data in the Store by one or more of its properties. Example usage:</p>
-<pre><code>
-//sort by a single field
-myStore.sort('myField', 'DESC');
-
-//sorting by multiple fields
-myStore.sort([
- {
- property : 'age',
- direction: 'ASC'
- },
- {
- property : 'name',
- direction: 'DESC'
- }
-]);
-</code></pre>
- * <p>Internally, Store converts the passed arguments into an array of {@link Ext.util.Sorter} instances, and delegates the actual
- * sorting to its internal {@link Ext.util.MixedCollection}.</p>
- * <p>When passing a single string argument to sort, Store maintains a ASC/DESC toggler per field, so this code:</p>
-<pre><code>
-store.sort('myField');
-store.sort('myField');
- </code></pre>
- * <p>Is equivalent to this code, because Store handles the toggling automatically:</p>
-<pre><code>
-store.sort('myField', 'ASC');
-store.sort('myField', 'DESC');
-</code></pre>
- * @param {String|Array} sorters Either a string name of one of the fields in this Store's configured {@link Ext.data.Model Model},
- * or an Array of sorter configurations.
+ * Sorts the data in the Store by one or more of its properties. Example usage:
+ *
+ * //sort by a single field
+ * myStore.sort('myField', 'DESC');
+ *
+ * //sorting by multiple fields
+ * myStore.sort([
+ * {
+ * property : 'age',
+ * direction: 'ASC'
+ * },
+ * {
+ * property : 'name',
+ * direction: 'DESC'
+ * }
+ * ]);
+ *
+ * Internally, Store converts the passed arguments into an array of {@link Ext.util.Sorter} instances, and delegates
+ * the actual sorting to its internal {@link Ext.util.MixedCollection}.
+ *
+ * When passing a single string argument to sort, Store maintains a ASC/DESC toggler per field, so this code:
+ *
+ * store.sort('myField');
+ * store.sort('myField');
+ *
+ * Is equivalent to this code, because Store handles the toggling automatically:
+ *
+ * store.sort('myField', 'ASC');
+ * store.sort('myField', 'DESC');
+ *
+ * @param {String/Ext.util.Sorter[]} sorters Either a string name of one of the fields in this Store's configured
+ * {@link Ext.data.Model Model}, or an array of sorter configurations.
* @param {String} direction The overall direction to sort the data by. Defaults to "ASC".
+ * @return {Ext.util.Sorter[]}
*/
sort: function(sorters, direction, where, doSort) {
var me = this,
sorter, sorterFn,
newSorters;
-
+
if (Ext.isArray(sorters)) {
doSort = where;
where = direction;
@@ -138,13 +135,13 @@ store.sort('myField', 'DESC');
sorter.setDirection(direction);
}
}
-
+
if (newSorters && newSorters.length) {
newSorters = me.decodeSorters(newSorters);
if (Ext.isString(where)) {
if (where === 'prepend') {
sorters = me.sorters.clone().items;
-
+
me.sorters.clear();
me.sorters.addAll(newSorters);
me.sorters.addAll(sorters);
@@ -157,13 +154,11 @@ store.sort('myField', 'DESC');
me.sorters.clear();
me.sorters.addAll(newSorters);
}
-
- if (doSort !== false) {
- me.onBeforeSort(newSorters);
- }
}
-
+
if (doSort !== false) {
+ me.onBeforeSort(newSorters);
+
sorters = me.sorters.items;
if (sorters.length) {
//construct an amalgamated sorter function which combines all of the Sorters passed
@@ -180,20 +175,20 @@ store.sort('myField', 'DESC');
return result;
};
- me.doSort(sorterFn);
+ me.doSort(sorterFn);
}
}
-
+
return sorters;
},
-
+
onBeforeSort: Ext.emptyFn,
-
+
/**
* @private
* Normalizes an array of sorter objects, ensuring that they are all Ext.util.Sorter instances
- * @param {Array} sorters The sorters array
- * @return {Array} Array of Ext.util.Sorter objects
+ * @param {Object[]} sorters The sorters array
+ * @return {Ext.util.Sorter[]} Array of Ext.util.Sorter objects
*/
decodeSorters: function(sorters) {
if (!Ext.isArray(sorters)) {
@@ -219,7 +214,7 @@ store.sort('myField', 'DESC');
property: config
};
}
-
+
Ext.applyIf(config, {
root : this.sortRoot,
direction: "ASC"
@@ -248,7 +243,7 @@ store.sort('myField', 'DESC');
return sorters;
},
-
+
getSorters: function() {
return this.sorters.items;
}