docs/source/Sorter.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='Ext-util-Sorter'>/**
  19 </span> * Represents a single sorter that can be applied to a Store. The sorter is used
  20  * to compare two values against each other for the purpose of ordering them. Ordering
  21  * is achieved by specifying either:
  22  *
  23  * - {@link #property A sorting property}
  24  * - {@link #sorterFn A sorting function}
  25  *
  26  * As a contrived example, we can specify a custom sorter that sorts by rank:
  27  *
  28  *     Ext.define('Person', {
  29  *         extend: 'Ext.data.Model',
  30  *         fields: ['name', 'rank']
  31  *     });
  32  *
  33  *     Ext.create('Ext.data.Store', {
  34  *         model: 'Person',
  35  *         proxy: 'memory',
  36  *         sorters: [{
  37  *             sorterFn: function(o1, o2){
  38  *                 var getRank = function(o){
  39  *                     var name = o.get('rank');
  40  *                     if (name === 'first') {
  41  *                         return 1;
  42  *                     } else if (name === 'second') {
  43  *                         return 2;
  44  *                     } else {
  45  *                         return 3;
  46  *                     }
  47  *                 },
  48  *                 rank1 = getRank(o1),
  49  *                 rank2 = getRank(o2);
  50  *
  51  *                 if (rank1 === rank2) {
  52  *                     return 0;
  53  *                 }
  54  *
  55  *                 return rank1 &lt; rank2 ? -1 : 1;
  56  *             }
  57  *         }],
  58  *         data: [{
  59  *             name: 'Person1',
  60  *             rank: 'second'
  61  *         }, {
  62  *             name: 'Person2',
  63  *             rank: 'third'
  64  *         }, {
  65  *             name: 'Person3',
  66  *             rank: 'first'
  67  *         }]
  68  *     });
  69  */
  70 Ext.define('Ext.util.Sorter', {
  71
  72 <span id='Ext-util-Sorter-cfg-property'>    /**
  73 </span>     * @cfg {String} property
  74      * The property to sort by. Required unless {@link #sorterFn} is provided. The property is extracted from the object
  75      * directly and compared for sorting using the built in comparison operators.
  76      */
  77
  78 <span id='Ext-util-Sorter-cfg-sorterFn'>    /**
  79 </span>     * @cfg {Function} sorterFn
  80      * A specific sorter function to execute. Can be passed instead of {@link #property}. This sorter function allows
  81      * for any kind of custom/complex comparisons. The sorterFn receives two arguments, the objects being compared. The
  82      * function should return:
  83      *
  84      *   - -1 if o1 is &quot;less than&quot; o2
  85      *   - 0 if o1 is &quot;equal&quot; to o2
  86      *   - 1 if o1 is &quot;greater than&quot; o2
  87      */
  88
  89 <span id='Ext-util-Sorter-cfg-root'>    /**
  90 </span>     * @cfg {String} root
  91      * Optional root property. This is mostly useful when sorting a Store, in which case we set the root to 'data' to
  92      * make the filter pull the {@link #property} out of the data object of each item
  93      */
  94
  95 <span id='Ext-util-Sorter-cfg-transform'>    /**
  96 </span>     * @cfg {Function} transform
  97      * A function that will be run on each value before it is compared in the sorter. The function will receive a single
  98      * argument, the value.
  99      */
 100
 101 <span id='Ext-util-Sorter-cfg-direction'>    /**
 102 </span>     * @cfg {String} direction
 103      * The direction to sort by.
 104      */
 105     direction: &quot;ASC&quot;,
 106
 107     constructor: function(config) {
 108         var me = this;
 109
 110         Ext.apply(me, config);
 111
 112         //&lt;debug&gt;
 113         if (me.property === undefined &amp;&amp; me.sorterFn === undefined) {
 114             Ext.Error.raise(&quot;A Sorter requires either a property or a sorter function&quot;);
 115         }
 116         //&lt;/debug&gt;
 117
 118         me.updateSortFunction();
 119     },
 120
 121 <span id='Ext-util-Sorter-method-createSortFunction'>    /**
 122 </span>     * @private
 123      * Creates and returns a function which sorts an array by the given property and direction
 124      * @return {Function} A function which sorts by the property/direction combination provided
 125      */
 126     createSortFunction: function(sorterFn) {
 127         var me        = this,
 128             property  = me.property,
 129             direction = me.direction || &quot;ASC&quot;,
 130             modifier  = direction.toUpperCase() == &quot;DESC&quot; ? -1 : 1;
 131
 132         //create a comparison function. Takes 2 objects, returns 1 if object 1 is greater,
 133         //-1 if object 2 is greater or 0 if they are equal
 134         return function(o1, o2) {
 135             return modifier * sorterFn.call(me, o1, o2);
 136         };
 137     },
 138
 139 <span id='Ext-util-Sorter-method-defaultSorterFn'>    /**
 140 </span>     * @private
 141      * Basic default sorter function that just compares the defined property of each object
 142      */
 143     defaultSorterFn: function(o1, o2) {
 144         var me = this,
 145             transform = me.transform,
 146             v1 = me.getRoot(o1)[me.property],
 147             v2 = me.getRoot(o2)[me.property];
 148
 149         if (transform) {
 150             v1 = transform(v1);
 151             v2 = transform(v2);
 152         }
 153
 154         return v1 &gt; v2 ? 1 : (v1 &lt; v2 ? -1 : 0);
 155     },
 156
 157 <span id='Ext-util-Sorter-method-getRoot'>    /**
 158 </span>     * @private
 159      * Returns the root property of the given item, based on the configured {@link #root} property
 160      * @param {Object} item The item
 161      * @return {Object} The root property of the object
 162      */
 163     getRoot: function(item) {
 164         return this.root === undefined ? item : item[this.root];
 165     },
 166
 167 <span id='Ext-util-Sorter-method-setDirection'>    /**
 168 </span>     * Set the sorting direction for this sorter.
 169      * @param {String} direction The direction to sort in. Should be either 'ASC' or 'DESC'.
 170      */
 171     setDirection: function(direction) {
 172         var me = this;
 173         me.direction = direction;
 174         me.updateSortFunction();
 175     },
 176
 177 <span id='Ext-util-Sorter-method-toggle'>    /**
 178 </span>     * Toggles the sorting direction for this sorter.
 179      */
 180     toggle: function() {
 181         var me = this;
 182         me.direction = Ext.String.toggle(me.direction, &quot;ASC&quot;, &quot;DESC&quot;);
 183         me.updateSortFunction();
 184     },
 185
 186 <span id='Ext-util-Sorter-method-updateSortFunction'>    /**
 187 </span>     * Update the sort function for this sorter.
 188      * @param {Function} [fn] A new sorter function for this sorter. If not specified it will use the default
 189      * sorting function.
 190      */
 191     updateSortFunction: function(fn) {
 192         var me = this;
 193         fn = fn || me.sorterFn || me.defaultSorterFn;
 194         me.sort = me.createSortFunction(fn);
 195     }
 196 });</pre>
 197 </body>
 198 </html>