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