Upgrade to ExtJS 4.0.2 - Released 06/09/2011

[extjs.git] / docs / source / Sorter.html

diff --git a/docs/source/Sorter.html b/docs/source/Sorter.html
index 161e812..b44375c 100644 (file)
--- a/docs/source/Sorter.html
+++ b/docs/source/Sorter.html
@@ -18,16 +18,76 @@
   <pre class="prettyprint lang-js"><span id='Ext-util-Sorter'>/**
 </span> * @class Ext.util.Sorter
  * @extends Object
- * Represents a single sorter that can be applied to a Store
+
+Represents a single sorter that can be applied to a Store. The sorter is used
+to compare two values against each other for the purpose of ordering them. Ordering
+is achieved by specifying either:
+- {@link #property A sorting property}
+- {@link #sorterFn A sorting function} 
+
+As a contrived example, we can specify a custom sorter that sorts by rank:
+
+    Ext.define('Person', {
+        extend: 'Ext.data.Model',
+        fields: ['name', 'rank']
+    });
+
+    Ext.create('Ext.data.Store', {
+        model: 'Person',
+        proxy: 'memory',
+        sorters: [{
+            sorterFn: function(o1, o2){
+                var getRank = function(o){
+                    var name = o.get('rank');
+                    if (name === 'first') {
+                        return 1;
+                    } else if (name === 'second') {
+                        return 2;
+                    } else {
+                        return 3;
+                    }
+                },
+                rank1 = getRank(o1),
+                rank2 = getRank(o2);
+                
+                if (rank1 === rank2) {
+                    return 0;
+                }
+                
+                return rank1 &lt; rank2 ? -1 : 1;
+            }
+        }],
+        data: [{
+            name: 'Person1',
+            rank: 'second'
+        }, {
+            name: 'Person2',
+            rank: 'third'
+        }, {
+            name: 'Person3',
+            rank: 'first'
+        }] 
+    });
+
+ * @markdown
  */
 Ext.define('Ext.util.Sorter', {
 
 <span id='Ext-util-Sorter-cfg-property'>    /**
-</span>     * @cfg {String} property The property to sort by. Required unless {@link #sorter} is provided
+</span>     * @cfg {String} property The property to sort by. Required unless {@link #sorterFn} is provided.
+     * The property is extracted from the object directly and compared for sorting using the built in
+     * comparison operators.
      */
     
 <span id='Ext-util-Sorter-cfg-sorterFn'>    /**
-</span>     * @cfg {Function} sorterFn A specific sorter function to execute. Can be passed instead of {@link #property}
+</span>     * @cfg {Function} sorterFn A specific sorter function to execute. Can be passed instead of {@link #property}.
+     * This sorter function allows for any kind of custom/complex comparisons.
+     * The sorterFn receives two arguments, the objects being compared. The function should return:
+     * &lt;ul&gt;
+     * &lt;li&gt;-1 if o1 is &quot;less than&quot; o2&lt;/li&gt;
+     * &lt;li&gt;0 if o1 is &quot;equal&quot; to o2&lt;/li&gt;
+     * &lt;li&gt;1 if o1 is &quot;greater than&quot; o2&lt;/li&gt;
+     * &lt;/ul&gt;
      */
     
 <span id='Ext-util-Sorter-cfg-root'>    /**
@@ -52,7 +112,7 @@ Ext.define('Ext.util.Sorter', {
         Ext.apply(me, config);
         
         //&lt;debug&gt;
-        if (me.property == undefined &amp;&amp; me.sorterFn == undefined) {
+        if (me.property === undefined &amp;&amp; me.sorterFn === undefined) {
             Ext.Error.raise(&quot;A Sorter requires either a property or a sorter function&quot;);
         }
         //&lt;/debug&gt;
@@ -103,25 +163,37 @@ Ext.define('Ext.util.Sorter', {
      * @return {Object} The root property of the object
      */
     getRoot: function(item) {
-        return this.root == undefined ? item : item[this.root];
+        return this.root === undefined ? item : item[this.root];
     },
     
-    // @TODO: Add docs for these three methods
+<span id='Ext-util-Sorter-method-setDirection'>    /**
+</span>     * Set the sorting direction for this sorter.
+     * @param {String} direction The direction to sort in. Should be either 'ASC' or 'DESC'.
+     */
     setDirection: function(direction) {
         var me = this;
         me.direction = direction;
         me.updateSortFunction();
     },
     
+<span id='Ext-util-Sorter-method-toggle'>    /**
+</span>     * Toggles the sorting direction for this sorter.
+     */
     toggle: function() {
         var me = this;
         me.direction = Ext.String.toggle(me.direction, &quot;ASC&quot;, &quot;DESC&quot;);
         me.updateSortFunction();
     },
     
-    updateSortFunction: function() {
+<span id='Ext-util-Sorter-method-updateSortFunction'>    /**
+</span>     * Update the sort function for this sorter.
+     * @param {Function} fn (Optional) A new sorter function for this sorter. If not specified it will use the
+     * default sorting function.
+     */
+    updateSortFunction: function(fn) {
         var me = this;
-        me.sort = me.createSortFunction(me.sorterFn || me.defaultSorterFn);
+        fn = fn || me.sorterFn || me.defaultSorterFn;
+        me.sort = me.createSortFunction(fn);
     }
 });</pre>
 </body>