jssource/src_files/include/javascript/yui3/build/recordset/recordset-sort.js

   1 /*
   2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.com/yui/license.html
   5 version: 3.3.0
   6 build: 3167
   7 */
   8 YUI.add('recordset-sort', function(Y) {
   9
  10 /**
  11  * Adds default and custom sorting functionality to the Recordset utility
  12  * @module recordset
  13  * @submodule recordset-sort
  14  */
  15
  16 var Compare = Y.ArraySort.compare,
  17 isValue = Y.Lang.isValue;
  18
  19 /**
  20  * Plugin that adds default and custom sorting functionality to the Recordset utility
  21  * @class RecordsetSort
  22  */
  23
  24 function RecordsetSort(field, desc, sorter) {
  25     RecordsetSort.superclass.constructor.apply(this, arguments);
  26 }
  27
  28 Y.mix(RecordsetSort, {
  29     NS: "sort",
  30
  31     NAME: "recordsetSort",
  32
  33     ATTRS: {
  34
  35         /**
  36             * @description The last properties used to sort. Consists of an object literal with the keys "field", "desc", and "sorter"
  37             *
  38             * @attribute lastSortProperties
  39             * @public
  40             * @type object
  41             */
  42         lastSortProperties: {
  43             value: {
  44                 field: undefined,
  45                 desc: true,
  46                 sorter: undefined
  47             },
  48             validator: function(v) {
  49                 return (isValue(v.field) && isValue(v.desc) && isValue(v.sorter));
  50             }
  51         },
  52
  53         /**
  54             * @description Default sort function to use if none is specified by the user.
  55                 * Takes two records, the key to sort by, and whether sorting direction is descending or not (boolean).
  56                 * If two records have the same value for a given key, the ID is used as the tie-breaker.
  57             *
  58             * @attribute defaultSorter
  59             * @public
  60             * @type function
  61             */
  62         defaultSorter: {
  63             value: function(recA, recB, field, desc) {
  64                 var sorted = Compare(recA.getValue(field), recB.getValue(field), desc);
  65                 if (sorted === 0) {
  66                     return Compare(recA.get("id"), recB.get("id"), desc);
  67                 }
  68                 else {
  69                     return sorted;
  70                 }
  71             }
  72         },
  73
  74         /**
  75             * @description A boolean telling if the recordset is in a sorted state.
  76             *
  77             * @attribute defaultSorter
  78             * @public
  79             * @type function
  80             */
  81         isSorted: {
  82             value: false
  83         }
  84     }
  85 });
  86
  87 Y.extend(RecordsetSort, Y.Plugin.Base, {
  88
  89     /**
  90      * @description Sets up the default function to use when the "sort" event is fired.
  91      *
  92      * @method initializer
  93      * @protected
  94      */
  95     initializer: function(config) {
  96
  97         var self = this,
  98         host = this.get('host');
  99
 100
 101         this.publish("sort", {
 102             defaultFn: Y.bind("_defSortFn", this)
 103         });
 104
 105         //Toggle the isSorted ATTR based on events.
 106         //Remove events dont affect isSorted, as they are just popped/sliced out
 107         this.on("sort",
 108         function() {
 109             self.set('isSorted', true);
 110         });
 111
 112         this.onHostEvent('add',
 113         function() {
 114             self.set('isSorted', false);
 115         },
 116         host);
 117         this.onHostEvent('update',
 118         function() {
 119             self.set('isSorted', false);
 120         },
 121         host);
 122
 123     },
 124
 125     destructor: function(config) {
 126         },
 127
 128     /**
 129      * @description Method that all sort calls go through.
 130          * Sets up the lastSortProperties object with the details of the sort, and passes in parameters
 131          * to the "defaultSorter" or a custom specified sort function.
 132      *
 133      * @method _defSortFn
 134      * @private
 135      */
 136     _defSortFn: function(e) {
 137         //have to work directly with _items here - changing the recordset.
 138         this.get("host")._items.sort(function(a, b) {
 139             return (e.sorter)(a, b, e.field, e.desc);
 140         });
 141
 142         this.set('lastSortProperties', e);
 143     },
 144
 145     /**
 146      * @description Sorts the recordset.
 147          *
 148          * @method sort
 149      * @param field {string} A key to sort by.
 150      * @param desc {boolean} True if you want sort order to be descending, false if you want sort order to be ascending
 151      * @public
 152      */
 153     sort: function(field, desc, sorter) {
 154         this.fire("sort", {
 155             field: field,
 156             desc: desc,
 157             sorter: sorter || this.get("defaultSorter")
 158         });
 159     },
 160
 161     /**
 162      * @description Resorts the recordset based on the last-used sort parameters (stored in 'lastSortProperties' ATTR)
 163          *
 164      * @method resort
 165      * @public
 166      */
 167     resort: function() {
 168         var p = this.get('lastSortProperties');
 169         this.fire("sort", {
 170             field: p.field,
 171             desc: p.desc,
 172             sorter: p.sorter || this.get("defaultSorter")
 173         });
 174     },
 175
 176     /**
 177      * @description Reverses the recordset calling the standard array.reverse() method.
 178          *
 179      * @method reverse
 180      * @public
 181      */
 182     reverse: function() {
 183         this.get('host')._items.reverse();
 184     },
 185
 186     /**
 187      * @description Sorts the recordset based on the last-used sort parameters, but flips the order. (ie: Descending becomes ascending, and vice versa).
 188          *
 189      * @method flip
 190      * @public
 191      */
 192     flip: function() {
 193         var p = this.get('lastSortProperties');
 194
 195         //If a predefined field is not provided by which to sort by, throw an error
 196         if (isValue(p.field)) {
 197             this.fire("sort", {
 198                 field: p.field,
 199                 desc: !p.desc,
 200                 sorter: p.sorter || this.get("defaultSorter")
 201             });
 202         }
 203         else {
 204         }
 205     }
 206 });
 207
 208 Y.namespace("Plugin").RecordsetSort = RecordsetSort;
 209
 210
 211
 212
 213 }, '3.3.0' ,{requires:['arraysort','recordset-base','plugin']});