<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>The source code</title>
- <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
- <script type="text/javascript" src="../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>
</head>
<body onload="prettyPrint(); highlight();">
<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
+</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 < rank2 ? -1 : 1;
+ * }
+ * }],
+ * data: [{
+ * name: 'Person1',
+ * rank: 'second'
+ * }, {
+ * name: 'Person2',
+ * rank: 'third'
+ * }, {
+ * name: 'Person3',
+ * rank: 'first'
+ * }]
+ * });
*/
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:
+ *
+ * - -1 if o1 is "less than" o2
+ * - 0 if o1 is "equal" to o2
+ * - 1 if o1 is "greater than" 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> * @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> * @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. Defaults to ASC
+</span> * @cfg {String} direction
+ * The direction to sort by.
*/
direction: "ASC",
Ext.apply(me, config);
//<debug>
- if (me.property == undefined && me.sorterFn == undefined) {
+ if (me.property === undefined && me.sorterFn === undefined) {
Ext.Error.raise("A Sorter requires either a property or a sorter function");
}
//</debug>
* @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, "ASC", "DESC");
me.updateSortFunction();
},
- updateSortFunction: function() {
+<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;
- me.sort = me.createSortFunction(me.sorterFn || me.defaultSorterFn);
+ fn = fn || me.sorterFn || me.defaultSorterFn;
+ me.sort = me.createSortFunction(fn);
}
});</pre>
</body>
git.ithinksw.org / extjs.git / blobdiff