/*
|
This file is part of Ext JS 4.2
|
|
Copyright (c) 2011-2013 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.
|
|
Build date: 2013-05-16 14:36:50 (f9be68accb407158ba2b1be2c226a6ce1f649314)
|
*/
|
/**
|
* Represents a single sorter that can be applied to a Store. The sorter is used
|
* to compare two values against each other for the purpose of ordering them. Ordering
|
* is achieved by specifying either:
|
*
|
* - {@link #property A sorting property}
|
* - {@link #sorterFn A sorting function}
|
*
|
* As a contrived example, we can specify a custom sorter that sorts by rank:
|
*
|
* Ext.define('Person', {
|
* extend: 'Ext.data.Model',
|
* fields: ['name', 'rank']
|
* });
|
*
|
* Ext.create('Ext.data.Store', {
|
* model: 'Person',
|
* proxy: 'memory',
|
* sorters: [{
|
* sorterFn: function(o1, o2){
|
* var getRank = function(o){
|
* var name = o.get('rank');
|
* if (name === 'first') {
|
* return 1;
|
* } else if (name === 'second') {
|
* return 2;
|
* } else {
|
* return 3;
|
* }
|
* },
|
* rank1 = getRank(o1),
|
* rank2 = getRank(o2);
|
*
|
* if (rank1 === rank2) {
|
* return 0;
|
* }
|
*
|
* return rank1 < rank2 ? -1 : 1;
|
* }
|
* }],
|
* data: [{
|
* name: 'Person1',
|
* rank: 'second'
|
* }, {
|
* name: 'Person2',
|
* rank: 'third'
|
* }, {
|
* name: 'Person3',
|
* rank: 'first'
|
* }]
|
* });
|
*/
|
Ext.define('Ext.util.Sorter', {
|
|
/**
|
* @cfg {String} property
|
* The property to sort by. Required unless {@link #sorterFn} is provided. The property is extracted from the object
|
* directly and compared for sorting using the built in comparison operators.
|
*/
|
|
/**
|
* @cfg {Function} sorterFn
|
* A specific sorter function to execute. Can be passed instead of {@link #property}. This sorter function allows
|
* for any kind of custom/complex comparisons. The sorterFn receives two arguments, the objects being compared. The
|
* function should return:
|
*
|
* - -1 if o1 is "less than" o2
|
* - 0 if o1 is "equal" to o2
|
* - 1 if o1 is "greater than" o2
|
*/
|
|
/**
|
* @cfg {String} root
|
* Optional root property. This is mostly useful when sorting a Store, in which case we set the root to 'data' to
|
* make the filter pull the {@link #property} out of the data object of each item
|
*/
|
|
/**
|
* @cfg {Function} transform
|
* A function that will be run on each value before it is compared in the sorter. The function will receive a single
|
* argument, the value.
|
*/
|
|
/**
|
* @cfg {String} direction
|
* The direction to sort by.
|
*/
|
direction: "ASC",
|
|
constructor: function(config) {
|
var me = this;
|
|
Ext.apply(me, config);
|
|
//<debug>
|
if (me.property === undefined && me.sorterFn === undefined) {
|
Ext.Error.raise("A Sorter requires either a property or a sorter function");
|
}
|
//</debug>
|
|
me.updateSortFunction();
|
},
|
|
/**
|
* @private
|
* Creates and returns a function which sorts an array by the given property and direction
|
* @return {Function} A function which sorts by the property/direction combination provided
|
*/
|
createSortFunction: function(sorterFn) {
|
var me = this,
|
direction = me.direction || "ASC",
|
modifier = direction.toUpperCase() == "DESC" ? -1 : 1;
|
|
//create a comparison function. Takes 2 objects, returns 1 if object 1 is greater,
|
//-1 if object 2 is greater or 0 if they are equal
|
return function(o1, o2) {
|
return modifier * sorterFn.call(me, o1, o2);
|
};
|
},
|
|
/**
|
* @private
|
* Basic default sorter function that just compares the defined property of each object
|
*/
|
defaultSorterFn: function(o1, o2) {
|
var me = this,
|
transform = me.transform,
|
v1 = me.getRoot(o1)[me.property],
|
v2 = me.getRoot(o2)[me.property];
|
|
if (transform) {
|
v1 = transform(v1);
|
v2 = transform(v2);
|
}
|
|
return v1 > v2 ? 1 : (v1 < v2 ? -1 : 0);
|
},
|
|
/**
|
* @private
|
* Returns the root property of the given item, based on the configured {@link #root} property
|
* @param {Object} item The item
|
* @return {Object} The root property of the object
|
*/
|
getRoot: function(item) {
|
return this.root === undefined ? item : item[this.root];
|
},
|
|
/**
|
* Set the sorting direction for this sorter.
|
* @param {String} direction The direction to sort in. Should be either 'ASC' or 'DESC'.
|
*/
|
setDirection: function(direction) {
|
var me = this;
|
me.direction = direction ? direction.toUpperCase() : direction;
|
me.updateSortFunction();
|
},
|
|
/**
|
* Toggles the sorting direction for this sorter.
|
*/
|
toggle: function() {
|
var me = this;
|
me.direction = Ext.String.toggle(me.direction, "ASC", "DESC");
|
me.updateSortFunction();
|
},
|
|
/**
|
* Update the sort function for this sorter.
|
* @param {Function} [fn] A new sorter function for this sorter. If not specified it will use the default
|
* sorting function.
|
*/
|
updateSortFunction: function(fn) {
|
var me = this;
|
fn = fn || me.sorterFn || me.defaultSorterFn;
|
me.sort = me.createSortFunction(fn);
|
},
|
|
serialize: function() {
|
return {
|
root: this.root,
|
property: this.property,
|
direction: this.direction
|
};
|
}
|
});
|
