X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/6746dc89c47ed01b165cc1152533605f97eb8e8d..f562e4c6e5fac7bcb445985b99acbea4d706e6f0:/src/util/Sortable.js diff --git a/src/util/Sortable.js b/src/util/Sortable.js index 2cd2025a..6e4fd905 100644 --- a/src/util/Sortable.js +++ b/src/util/Sortable.js @@ -13,101 +13,98 @@ If you are unsure which license is appropriate for your use, please contact the */ /** - * @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 + * + * 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' ], /** + * @property {String} sortRoot * The property in each item that contains the data to sort. - * @type String - */ - + */ + /** - * 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; - + /** + * @property {Ext.util.MixedCollection} sorters * The collection of {@link Ext.util.Sorter Sorters} currently applied to this Store - * @property sorters - * @type Ext.util.MixedCollection */ me.sorters = Ext.create('Ext.util.AbstractMixedCollection', false, function(item) { return item.id || item.property; }); - + if (sorters) { me.sorters.addAll(me.decodeSorters(sorters)); } }, /** - *

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|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; @@ -135,13 +132,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); @@ -154,13 +151,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 @@ -177,20 +172,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)) { @@ -216,7 +211,7 @@ store.sort('myField', 'DESC'); property: config }; } - + Ext.applyIf(config, { root : this.sortRoot, direction: "ASC" @@ -245,7 +240,7 @@ store.sort('myField', 'DESC'); return sorters; }, - + getSorters: function() { return this.sorters.items; }