add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / util / Grouper.js

/**\r
 * Represents a grouping of items. The grouper works in a similar fashion as the\r
 * `Ext.util.Sorter` except that groups must be able to extract a value by which all items\r
 * in the group can be collected. By default this is derived from the `property` config\r
 * but can be customized using the `groupFn` if necessary.\r
 *\r
 * All items with the same group value compare as equal. If the group values do not compare\r
 * equally, the sort can be controlled further by setting `sortProperty` or `sorterFn`.\r
 */\r
Ext.define('Ext.util.Grouper', {\r
    extend: 'Ext.util.Sorter',\r
\r
    isGrouper: true,\r
\r
    config: {\r
        /**\r
         * @cfg {Function} groupFn This function is called for each item in the collection\r
         * to determine the group to which it belongs. By default the `property` value is\r
         * used to group items.\r
         * @cfg {Object} groupFn.item The current item from the collection.\r
         * @cfg {String} groupFn.return The group identifier for the item.\r
         */\r
        groupFn: null,\r
\r
        /**\r
         * @cfg {String} property The field by which records are grouped. Groups are \r
         * sorted alphabetically by group value as the default. To sort groups by a different \r
         * property, use the {@link #sortProperty} configuration.\r
         */\r
\r
        /**\r
         * @cfg {String} sortProperty You can set this configuration if you want the groups\r
         * to be sorted on something other then the group string returned by the `groupFn`.\r
         * This serves the same role as `property` on a normal `Ext.util.Sorter`.\r
         */\r
        sortProperty: null\r
    },\r
\r
    constructor: function(config) {\r
        //<debug>\r
        if (config) {\r
            if (config.getGroupString) {\r
                Ext.raise("Cannot set getGroupString - use groupFn instead");\r
            }\r
        }\r
        //</debug>\r
\r
        this.callParent(arguments);\r
    },\r
\r
    /**\r
     * Returns the value for grouping to be used.\r
     * @param {Ext.data.Model} item The Model instance\r
     * @return {String}\r
     */\r
    getGroupString: function (item) {\r
        var group = this._groupFn(item);\r
        return (group != null) ? String(group) : '';\r
    },\r
\r
    sortFn: function (item1, item2) {\r
        var me = this,\r
            lhs = me._groupFn(item1),\r
            rhs = me._groupFn(item2),\r
            property = me._sortProperty, // Sorter's sortFn uses "_property"\r
            root = me._root,\r
            sorterFn = me._sorterFn,\r
            transform = me._transform;\r
\r
        // Items with the same groupFn result must be equal... otherwise we sort them\r
        // by sorterFn or sortProperty.\r
        if (lhs === rhs) {\r
            return 0;\r
        }\r
\r
        if (property || sorterFn) {\r
            if (sorterFn) {\r
                return sorterFn.call(this, item1, item2);\r
            }\r
\r
            if (root) {\r
                item1 = item1[root];\r
                item2 = item2[root];\r
            }\r
\r
            lhs = item1[property];\r
            rhs = item2[property];\r
\r
            if (transform) {\r
                lhs = transform(lhs);\r
                rhs = transform(rhs);\r
            }\r
        }\r
\r
        return (lhs > rhs) ? 1 : (lhs < rhs ? -1 : 0);\r
    },\r
\r
    standardGroupFn: function (item) {\r
        var root = this._root;\r
        return (root ? item[root] : item)[this._property];\r
    },\r
\r
    updateSorterFn: function () {\r
        // don't callParent here - we don't want to smash sortFn w/sorterFn\r
    },\r
\r
    updateProperty: function () {\r
        // we don't callParent since that is related to sorterFn smashing sortFn\r
        if (!this.getGroupFn()) {\r
            this.setGroupFn(this.standardGroupFn);\r
        }\r
    }\r
});\r