2 Copyright (c) 2010, Yahoo! Inc. All rights reserved.
3 Code licensed under the BSD License:
4 http://developer.yahoo.com/yui/license.html
8 YUI.add('recordset-sort', function(Y) {
11 * Adds default and custom sorting functionality to the Recordset utility
13 * @submodule recordset-sort
16 var Compare = Y.ArraySort.compare,
17 isValue = Y.Lang.isValue;
20 * Plugin that adds default and custom sorting functionality to the Recordset utility
21 * @class RecordsetSort
24 function RecordsetSort(field, desc, sorter) {
25 RecordsetSort.superclass.constructor.apply(this, arguments);
28 Y.mix(RecordsetSort, {
31 NAME: "recordsetSort",
36 * @description The last properties used to sort. Consists of an object literal with the keys "field", "desc", and "sorter"
38 * @attribute lastSortProperties
48 validator: function(v) {
49 return (isValue(v.field) && isValue(v.desc) && isValue(v.sorter));
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.
58 * @attribute defaultSorter
63 value: function(recA, recB, field, desc) {
64 var sorted = Compare(recA.getValue(field), recB.getValue(field), desc);
66 return Compare(recA.get("id"), recB.get("id"), desc);
75 * @description A boolean telling if the recordset is in a sorted state.
77 * @attribute defaultSorter
87 Y.extend(RecordsetSort, Y.Plugin.Base, {
90 * @description Sets up the default function to use when the "sort" event is fired.
95 initializer: function(config) {
98 host = this.get('host');
101 this.publish("sort", {
102 defaultFn: Y.bind("_defSortFn", this)
105 //Toggle the isSorted ATTR based on events.
106 //Remove events dont affect isSorted, as they are just popped/sliced out
109 self.set('isSorted', true);
112 this.onHostEvent('add',
114 self.set('isSorted', false);
117 this.onHostEvent('update',
119 self.set('isSorted', false);
125 destructor: function(config) {
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.
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);
142 this.set('lastSortProperties', e);
146 * @description Sorts the recordset.
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
153 sort: function(field, desc, sorter) {
157 sorter: sorter || this.get("defaultSorter")
162 * @description Resorts the recordset based on the last-used sort parameters (stored in 'lastSortProperties' ATTR)
168 var p = this.get('lastSortProperties');
172 sorter: p.sorter || this.get("defaultSorter")
177 * @description Reverses the recordset calling the standard array.reverse() method.
182 reverse: function() {
183 this.get('host')._items.reverse();
187 * @description Sorts the recordset based on the last-used sort parameters, but flips the order. (ie: Descending becomes ascending, and vice versa).
193 var p = this.get('lastSortProperties');
195 //If a predefined field is not provided by which to sort by, throw an error
196 if (isValue(p.field)) {
200 sorter: p.sorter || this.get("defaultSorter")
208 Y.namespace("Plugin").RecordsetSort = RecordsetSort;
213 }, '3.3.0' ,{requires:['arraysort','recordset-base','plugin']});