/*! - * Ext JS Library 3.2.1 - * Copyright(c) 2006-2010 Ext JS, Inc. - * licensing@extjs.com - * http://www.extjs.com/license - */ -/** - * @class Ext.list.Sorter - * @extends Ext.util.Observable - *- \ No newline at end of file +Supporting Class for Ext.list.ListView
- * @constructor - * @param {Object} config + +/** + * 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.list.Sorter = Ext.extend(Ext.util.Observable, { - /** - * @cfg {Array} sortClasses - * The CSS classes applied to a header when it is sorted. (defaults to ["sort-asc", "sort-desc"]) - */ - sortClasses : ["sort-asc", "sort-desc"], +Ext.define('Ext.util.Sorter', { - constructor: function(config){ - Ext.apply(this, config); - Ext.list.Sorter.superclass.constructor.call(this); + /** + * @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(); }, - - init : function(listView){ - this.view = listView; - listView.on('render', this.initEvents, this); + + /** + * @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, + property = me.property, + 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); + } - initEvents : function(view){ - view.mon(view.innerHd, 'click', this.onHdClick, this); - view.innerHd.setStyle('cursor', 'pointer'); - view.mon(view.store, 'datachanged', this.updateSortState, this); - this.updateSortState.defer(10, this, [view.store]); + return v1 > v2 ? 1 : (v1 < v2 ? -1 : 0); }, - - updateSortState : function(store){ - var state = store.getSortState(); - if(!state){ - return; - } - this.sortState = state; - var cs = this.view.columns, sortColumn = -1; - for(var i = 0, len = cs.length; i < len; i++){ - if(cs[i].dataIndex == state.field){ - sortColumn = i; - break; - } - } - if(sortColumn != -1){ - var sortDir = state.direction; - this.updateSortIcon(sortColumn, sortDir); - } + + /** + * @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]; }, - - updateSortIcon : function(col, dir){ - var sc = this.sortClasses; - var hds = this.view.innerHd.select('em').removeClass(sc); - hds.item(col).addClass(sc[dir == "DESC" ? 1 : 0]); + + /** + * 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; + me.updateSortFunction(); }, - - onHdClick : function(e){ - var hd = e.getTarget('em', 3); - if(hd && !this.view.disableHeaders){ - var index = this.view.findHeaderIndex(hd); - this.view.store.sort(this.view.columns[index].dataIndex); - } + + /** + * 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); } -}); - -// Backwards compatibility alias -Ext.ListView.Sorter = Ext.list.Sorter;+});