1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-util.Sortable'>/**
2 </span> * @class Ext.util.Sortable
4 A mixin which allows a data component to be sorted. This is used by e.g. {@link Ext.data.Store} and {@link Ext.data.TreeStore}.
6 **NOTE**: This mixin is mainly for internal library use and most users should not need to use it directly. It
7 is more likely you will want to use one of the component classes that import this mixin, such as
8 {@link Ext.data.Store} or {@link Ext.data.TreeStore}.
10 * @docauthor Tommy Maintz <tommy@sencha.com>
12 Ext.define("Ext.util.Sortable", {
13 <span id='Ext-util.Sortable-property-isSortable'> /**
14 </span> * @property isSortable
16 * Flag denoting that this object is sortable. Always true.
20 <span id='Ext-util.Sortable-property-defaultSortDirection'> /**
21 </span> * The default sort direction to use if one is not specified (defaults to "ASC")
22 * @property defaultSortDirection
25 defaultSortDirection: "ASC",
31 <span id='Ext-util.Sortable-property-sortRoot'> /**
32 </span> * The property in each item that contains the data to sort. (defaults to null)
37 <span id='Ext-util.Sortable-method-initSortable'> /**
38 </span> * Performs initialization of this mixin. Component classes using this mixin should call this method
39 * during their own initialization.
41 initSortable: function() {
45 <span id='Ext-util.Sortable-property-sorters'> /**
46 </span> * The collection of {@link Ext.util.Sorter Sorters} currently applied to this Store
48 * @type Ext.util.MixedCollection
50 me.sorters = Ext.create('Ext.util.AbstractMixedCollection', false, function(item) {
51 return item.id || item.property;
55 me.sorters.addAll(me.decodeSorters(sorters));
59 <span id='Ext-util.Sortable-method-sort'> /**
60 </span> * <p>Sorts the data in the Store by one or more of its properties. Example usage:</p>
61 <pre><code>
62 //sort by a single field
63 myStore.sort('myField', 'DESC');
65 //sorting by multiple fields
76 </code></pre>
77 * <p>Internally, Store converts the passed arguments into an array of {@link Ext.util.Sorter} instances, and delegates the actual
78 * sorting to its internal {@link Ext.util.MixedCollection}.</p>
79 * <p>When passing a single string argument to sort, Store maintains a ASC/DESC toggler per field, so this code:</p>
80 <pre><code>
81 store.sort('myField');
82 store.sort('myField');
83 </code></pre>
84 * <p>Is equivalent to this code, because Store handles the toggling automatically:</p>
85 <pre><code>
86 store.sort('myField', 'ASC');
87 store.sort('myField', 'DESC');
88 </code></pre>
89 * @param {String|Array} sorters Either a string name of one of the fields in this Store's configured {@link Ext.data.Model Model},
90 * or an Array of sorter configurations.
91 * @param {String} direction The overall direction to sort the data by. Defaults to "ASC".
93 sort: function(sorters, direction, where, doSort) {
98 if (Ext.isArray(sorters)) {
101 newSorters = sorters;
103 else if (Ext.isObject(sorters)) {
106 newSorters = [sorters];
108 else if (Ext.isString(sorters)) {
109 sorter = me.sorters.get(sorters);
116 newSorters = [sorter];
118 else if (direction === undefined) {
122 sorter.setDirection(direction);
126 if (newSorters && newSorters.length) {
127 newSorters = me.decodeSorters(newSorters);
128 if (Ext.isString(where)) {
129 if (where === 'prepend') {
130 sorters = me.sorters.clone().items;
133 me.sorters.addAll(newSorters);
134 me.sorters.addAll(sorters);
137 me.sorters.addAll(newSorters);
142 me.sorters.addAll(newSorters);
145 if (doSort !== false) {
146 me.onBeforeSort(newSorters);
150 if (doSort !== false) {
151 sorters = me.sorters.items;
152 if (sorters.length) {
153 //construct an amalgamated sorter function which combines all of the Sorters passed
154 sorterFn = function(r1, r2) {
155 var result = sorters[0].sort(r1, r2),
156 length = sorters.length,
159 //if we have more than one sorter, OR any additional sorter functions together
160 for (i = 1; i < length; i++) {
161 result = result || sorters[i].sort.call(this, r1, r2);
174 onBeforeSort: Ext.emptyFn,
176 <span id='Ext-util.Sortable-method-decodeSorters'> /**
178 * Normalizes an array of sorter objects, ensuring that they are all Ext.util.Sorter instances
179 * @param {Array} sorters The sorters array
180 * @return {Array} Array of Ext.util.Sorter objects
182 decodeSorters: function(sorters) {
183 if (!Ext.isArray(sorters)) {
184 if (sorters === undefined) {
191 var length = sorters.length,
192 Sorter = Ext.util.Sorter,
193 fields = this.model ? this.model.prototype.fields : null,
197 for (i = 0; i < length; i++) {
200 if (!(config instanceof Sorter)) {
201 if (Ext.isString(config)) {
207 Ext.applyIf(config, {
208 root : this.sortRoot,
209 direction: "ASC"
212 //support for 3.x style sorters where a function can be defined as 'fn'
214 config.sorterFn = config.fn;
217 //support a function to be passed as a sorter definition
218 if (typeof config == 'function') {
224 // ensure sortType gets pushed on if necessary
225 if (fields && !config.transform) {
226 field = fields.get(config.property);
227 config.transform = field ? field.sortType : undefined;
229 sorters[i] = Ext.create('Ext.util.Sorter', config);
236 getSorters: function() {
237 return this.sorters.items;
240 <span id='Ext-util.Sortable-method-getSortState'> /**
241 </span> * Returns an object describing the current sort state of this Store.
242 * @return {Object} The sort state of the Store. An object with two properties:<ul>
243 * <li><b>field</b> : String<p class="sub-desc">The name of the field by which the Records are sorted.</p></li>
244 * <li><b>direction</b> : String<p class="sub-desc">The sort order, 'ASC' or 'DESC' (case-sensitive).</p></li>
246 * See <tt>{@link #sortInfo}</tt> for additional details.
248 getSortState : function() {
249 return this.sortInfo;
251 });</pre></pre></body></html>