[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 Yahoo! Inc. All rights reserved.
   4  Licensed under the BSD License.
   5  http://yuilibrary.com/license/
   6  */
   7  
   8  YUI.add('recordset-sort', function (Y, NAME) {
   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              Y.log('You called flip before setting a field by which to sort by. Maybe you meant to call reverse().');
 205          }
 206      }
 207  });
 208  
 209  Y.namespace("Plugin").RecordsetSort = RecordsetSort;
 210  
 211  
 212  
 213  }, '3.17.2', {"requires": ["arraysort", "recordset-base", "plugin"]});