X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/7a654f8d43fdb43d78b63d90528bed6e86b608cc..6746dc89c47ed01b165cc1152533605f97eb8e8d:/docs/source/Sorter.html diff --git a/docs/source/Sorter.html b/docs/source/Sorter.html index fdfa7f26..b44375c3 100644 --- a/docs/source/Sorter.html +++ b/docs/source/Sorter.html @@ -1,30 +1,107 @@ -
/**
+
+
+
+
+ The source code
+
+
+
+
+
+
+ /**
* @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:
+ * <ul>
+ * <li>-1 if o1 is "less than" o2</li>
+ * <li>0 if o1 is "equal" to o2</li>
+ * <li>1 if o1 is "greater than" o2</li>
+ * </ul>
*/
- /**
+ /**
* @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. Defaults to ASC
*/
direction: "ASC",
@@ -35,7 +112,7 @@ Ext.define('Ext.util.Sorter', {
Ext.apply(me, config);
//<debug>
- if (me.property == undefined && me.sorterFn == undefined) {
+ if (me.property === undefined && me.sorterFn === undefined) {
Ext.Error.raise("A Sorter requires either a property or a sorter function");
}
//</debug>
@@ -43,7 +120,7 @@ Ext.define('Ext.util.Sorter', {
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
@@ -61,7 +138,7 @@ Ext.define('Ext.util.Sorter', {
};
},
- /**
+ /**
* @private
* Basic default sorter function that just compares the defined property of each object
*/
@@ -79,31 +156,45 @@ Ext.define('Ext.util.Sorter', {
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];
+ return this.root === undefined ? item : item[this.root];
},
- // @TODO: Add docs for these three methods
+ /**
+ * 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();
},
+ /**
+ * Toggles the sorting direction for this sorter.
+ */
toggle: function() {
var me = this;
me.direction = Ext.String.toggle(me.direction, "ASC", "DESC");
me.updateSortFunction();
},
- updateSortFunction: function() {
+ /**
+ * Update the sort function for this sorter.
+ * @param {Function} fn (Optional) A new sorter function for this sorter. If not specified it will use the
+ * default sorting function.
+ */
+ updateSortFunction: function(fn) {
var me = this;
- me.sort = me.createSortFunction(me.sorterFn || me.defaultSorterFn);
+ fn = fn || me.sorterFn || me.defaultSorterFn;
+ me.sort = me.createSortFunction(fn);
}
-});
\ No newline at end of file
+});
+
+