Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Sorter.html
index 517855a..1ac2ef3 100644 (file)
+<!DOCTYPE html>
 <html>
 <head>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
 </head>
-<body  onload="prettyPrint();">
-    <pre class="prettyprint lang-js">/*!
- * Ext JS Library 3.3.0
- * Copyright(c) 2006-2010 Ext JS, Inc.
- * licensing@extjs.com
- * http://www.extjs.com/license
- */
-<div id="cls-Ext.list.Sorter"></div>/**
- * @class Ext.list.Sorter
- * @extends Ext.util.Observable
- * <p>Supporting Class for Ext.list.ListView</p>
- * @constructor
- * @param {Object} config
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-util-Sorter'>/**
+</span> * 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'
+ *         }]
+ *     });
  */
-Ext.list.Sorter = Ext.extend(Ext.util.Observable, {
-    <div id="cfg-Ext.list.Sorter-sortClasses"></div>/**
-     * @cfg {Array} sortClasses
-     * The CSS classes applied to a header when it is sorted. (defaults to <tt>["sort-asc", "sort-desc"]</tt>)
-     */
-    sortClasses : ["sort-asc", "sort-desc"],
+Ext.define('Ext.util.Sorter', {
 
-    constructor: function(config){
-        Ext.apply(this, config);
-        Ext.list.Sorter.superclass.constructor.call(this);
+<span id='Ext-util-Sorter-cfg-property'>    /**
+</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}. This sorter function allows
+     * for any kind of custom/complex comparisons. The sorterFn receives two arguments, the objects being compared. The
+     * function should return:
+     *
+     *   - -1 if o1 is &quot;less than&quot; o2
+     *   - 0 if o1 is &quot;equal&quot; to o2
+     *   - 1 if o1 is &quot;greater than&quot; o2
+     */
+    
+<span id='Ext-util-Sorter-cfg-root'>    /**
+</span>     * @cfg {String} root
+     * Optional root property. This is mostly useful when sorting a Store, in which case we set the root to 'data' to
+     * make the filter pull the {@link #property} out of the data object of each item
+     */
+    
+<span id='Ext-util-Sorter-cfg-transform'>    /**
+</span>     * @cfg {Function} transform
+     * A function that will be run on each value before it is compared in the sorter. The function will receive a single
+     * argument, the value.
+     */
+    
+<span id='Ext-util-Sorter-cfg-direction'>    /**
+</span>     * @cfg {String} direction
+     * The direction to sort by.
+     */
+    direction: &quot;ASC&quot;,
+    
+    constructor: function(config) {
+        var me = this;
+        
+        Ext.apply(me, config);
+        
+        //&lt;debug&gt;
+        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;
+        
+        me.updateSortFunction();
     },
-
-    init : function(listView){
-        this.view = listView;
-        listView.on('render', this.initEvents, this);
+    
+<span id='Ext-util-Sorter-method-createSortFunction'>    /**
+</span>     * @private
+     * Creates and returns a function which sorts an array by the given property and direction
+     * @return {Function} A function which sorts by the property/direction combination provided
+     */
+    createSortFunction: function(sorterFn) {
+        var me        = this,
+            property  = me.property,
+            direction = me.direction || &quot;ASC&quot;,
+            modifier  = direction.toUpperCase() == &quot;DESC&quot; ? -1 : 1;
+        
+        //create a comparison function. Takes 2 objects, returns 1 if object 1 is greater,
+        //-1 if object 2 is greater or 0 if they are equal
+        return function(o1, o2) {
+            return modifier * sorterFn.call(me, o1, o2);
+        };
     },
+    
+<span id='Ext-util-Sorter-method-defaultSorterFn'>    /**
+</span>     * @private
+     * Basic default sorter function that just compares the defined property of each object
+     */
+    defaultSorterFn: function(o1, o2) {
+        var me = this,
+            transform = me.transform,
+            v1 = me.getRoot(o1)[me.property],
+            v2 = me.getRoot(o2)[me.property];
+            
+        if (transform) {
+            v1 = transform(v1);
+            v2 = transform(v2);
+        }
 
-    initEvents : function(view){
-        view.mon(view.innerHd, 'click', this.onHdClick, this);
-        view.innerHd.setStyle('cursor', 'pointer');
-        view.mon(view.store, 'datachanged', this.updateSortState, this);
-        this.updateSortState.defer(10, this, [view.store]);
+        return v1 &gt; v2 ? 1 : (v1 &lt; v2 ? -1 : 0);
     },
-
-    updateSortState : function(store){
-        var state = store.getSortState();
-        if(!state){
-            return;
-        }
-        this.sortState = state;
-        var cs = this.view.columns, sortColumn = -1;
-        for(var i = 0, len = cs.length; i < len; i++){
-            if(cs[i].dataIndex == state.field){
-                sortColumn = i;
-                break;
-            }
-        }
-        if(sortColumn != -1){
-            var sortDir = state.direction;
-            this.updateSortIcon(sortColumn, sortDir);
-        }
+    
+<span id='Ext-util-Sorter-method-getRoot'>    /**
+</span>     * @private
+     * Returns the root property of the given item, based on the configured {@link #root} property
+     * @param {Object} item The item
+     * @return {Object} The root property of the object
+     */
+    getRoot: function(item) {
+        return this.root === undefined ? item : item[this.root];
     },
-
-    updateSortIcon : function(col, dir){
-        var sc = this.sortClasses;
-        var hds = this.view.innerHd.select('em').removeClass(sc);
-        hds.item(col).addClass(sc[dir == "DESC" ? 1 : 0]);
+    
+<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();
     },
-
-    onHdClick : function(e){
-        var hd = e.getTarget('em', 3);
-        if(hd && !this.view.disableHeaders){
-            var index = this.view.findHeaderIndex(hd);
-            this.view.store.sort(this.view.columns[index].dataIndex);
-        }
+    
+<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();
+    },
+    
+<span id='Ext-util-Sorter-method-updateSortFunction'>    /**
+</span>     * Update the sort function for this sorter.
+     * @param {Function} [fn] A new sorter function for this sorter. If not specified it will use the default
+     * sorting function.
+     */
+    updateSortFunction: function(fn) {
+        var me = this;
+        fn = fn || me.sorterFn || me.defaultSorterFn;
+        me.sort = me.createSortFunction(fn);
     }
-});
-
-// Backwards compatibility alias
-Ext.ListView.Sorter = Ext.list.Sorter;</pre>    
+});</pre>
 </body>
-</html>
\ No newline at end of file
+</html>