X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/3789b528d8dd8aad4558e38e22d775bcab1cbd36..6746dc89c47ed01b165cc1152533605f97eb8e8d:/src/util/Sorter.js diff --git a/src/util/Sorter.js b/src/util/Sorter.js index 14fb112c..aaa0f4df 100644 --- a/src/util/Sorter.js +++ b/src/util/Sorter.js @@ -1,16 +1,90 @@ +/* + +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.util.Sorter * @extends Object - * Represents a single sorter that can be applied to a Store + +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' + }] + }); + + * @markdown */ Ext.define('Ext.util.Sorter', { /** - * @cfg {String} property The property to sort by. Required unless {@link #sorter} is provided + * @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} + * @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: + *