src/util/Sorter.js

   1 /**
   2  * @class Ext.util.Sorter
   3  * @extends Object
   4  * Represents a single sorter that can be applied to a Store
   5  */
   6 Ext.define('Ext.util.Sorter', {
   7
   8     /**
   9      * @cfg {String} property The property to sort by. Required unless {@link #sorter} is provided
  10      */
  11
  12     /**
  13      * @cfg {Function} sorterFn A specific sorter function to execute. Can be passed instead of {@link #property}
  14      */
  15
  16     /**
  17      * @cfg {String} root Optional root property. This is mostly useful when sorting a Store, in which case we set the
  18      * root to 'data' to make the filter pull the {@link #property} out of the data object of each item
  19      */
  20
  21     /**
  22      * @cfg {Function} transform A function that will be run on each value before
  23      * it is compared in the sorter. The function will receive a single argument,
  24      * the value.
  25      */
  26
  27     /**
  28      * @cfg {String} direction The direction to sort by. Defaults to ASC
  29      */
  30     direction: "ASC",
  31
  32     constructor: function(config) {
  33         var me = this;
  34
  35         Ext.apply(me, config);
  36
  37         //<debug>
  38         if (me.property == undefined && me.sorterFn == undefined) {
  39             Ext.Error.raise("A Sorter requires either a property or a sorter function");
  40         }
  41         //</debug>
  42
  43         me.updateSortFunction();
  44     },
  45
  46     /**
  47      * @private
  48      * Creates and returns a function which sorts an array by the given property and direction
  49      * @return {Function} A function which sorts by the property/direction combination provided
  50      */
  51     createSortFunction: function(sorterFn) {
  52         var me        = this,
  53             property  = me.property,
  54             direction = me.direction || "ASC",
  55             modifier  = direction.toUpperCase() == "DESC" ? -1 : 1;
  56
  57         //create a comparison function. Takes 2 objects, returns 1 if object 1 is greater,
  58         //-1 if object 2 is greater or 0 if they are equal
  59         return function(o1, o2) {
  60             return modifier * sorterFn.call(me, o1, o2);
  61         };
  62     },
  63
  64     /**
  65      * @private
  66      * Basic default sorter function that just compares the defined property of each object
  67      */
  68     defaultSorterFn: function(o1, o2) {
  69         var me = this,
  70             transform = me.transform,
  71             v1 = me.getRoot(o1)[me.property],
  72             v2 = me.getRoot(o2)[me.property];
  73
  74         if (transform) {
  75             v1 = transform(v1);
  76             v2 = transform(v2);
  77         }
  78
  79         return v1 > v2 ? 1 : (v1 < v2 ? -1 : 0);
  80     },
  81
  82     /**
  83      * @private
  84      * Returns the root property of the given item, based on the configured {@link #root} property
  85      * @param {Object} item The item
  86      * @return {Object} The root property of the object
  87      */
  88     getRoot: function(item) {
  89         return this.root == undefined ? item : item[this.root];
  90     },
  91
  92     // @TODO: Add docs for these three methods
  93     setDirection: function(direction) {
  94         var me = this;
  95         me.direction = direction;
  96         me.updateSortFunction();
  97     },
  98
  99     toggle: function() {
 100         var me = this;
 101         me.direction = Ext.String.toggle(me.direction, "ASC", "DESC");
 102         me.updateSortFunction();
 103     },
 104
 105     updateSortFunction: function() {
 106         var me = this;
 107         me.sort = me.createSortFunction(me.sorterFn || me.defaultSorterFn);
 108     }
 109 });