StoreSort

Configs

Common

sorters: Sorter[] | String[]Also a property

Initial sorters, format is:

{ sorters : [{ field: 'name', ascending: false }, ...] }
// or
{ sorters : ['name', ...] }

Advanced

useLocaleSort: Boolean | String | Object= false

Use localeCompare() when sorting, which lets the browser sort in a locale specific order. Set to true, a locale string or a locale config to enable.

Enabling this has big negative impact on sorting performance. For more info on localeCompare(), see MDN.

Examples:

const store = new Store({
    // Swedish sorting
    useLocaleSort : 'sv-SE'
});

const store = new Store({
    // Swedish sorting with custom casing order
    useLocaleSort : {
        locale    : 'sv-SE',
        caseFirst : 'upper'
    }
});

Can also be configured on a per-sorter basis:

store.sort({ field: 'name', useLocaleSort : 'sv-SE' });

Filtering

reapplySortersOnUpdate: Boolean | ObjectAlso a property

Specify true to reapply sorting when a record is updated in the store. You can also provide an array of field names, to only trigger sort when certain data fields are updated.

If the app processes many records or many record fields in a loop or similar, be sure to temporarily disable this setting. Otherwise, each change will trigger a sort, which will make the processing slow

Parameter	Type	Description
`reapplySortersOnUpdate.fields`	String[]	Fields that reapply sorting when updated

Sorting

reapplySortersOnAdd: Boolean= false

Specify true to sort this store after records are added.

remoteSort: Boolean

Set this to true to activate remote sorting in this Store. This makes it possible to use the built-in sorting features of the Store and corresponding UI functionality, without using local data.

For a non-AjaxStore, data will be requested by the Store by calling a by the app implemented requestData function. Data can also be provided by listening to the requestData event, and updating the data property with new data.

For AjaxStore, data will be loaded via the configured readUrl.

sortParamName: String

The name of the parameter to use to pass any sorters when loading data remotely.

Note: When this is set, sorters must be defined using a field name and an ascending flag, not a sort function.

Properties

Class hierarchy

isStoreSort: Boolean= truereadonly

Identifies an object as an instance of StoreSort class, or subclass thereof.

isStoreSort: Boolean= truereadonlystatic

Identifies an object as an instance of StoreSort class, or subclass thereof.

Filtering

reapplySortersOnUpdate: Boolean | ObjectAlso a config

Specify true to reapply sorting when a record is updated in the store. You can also provide an array of field names, to only trigger sort when certain data fields are updated.

Parameter	Type	Description
`reapplySortersOnUpdate.fields`	String[]	Fields that reapply sorting when updated

Sort, group & filter

isSorted: Booleanreadonly

Is store sorted?

sorters: Sorter[]readonlyAlso a config

Currently applied sorters

Functions

addSorter

Add a sorting level (a sorter).

Parameter	Type	Description
`field`	String \| Sorter[] \| Sorter \| function	Field to sort by. Can also be an array of sorters, or a sorting function, or a sorter config.
`ascending`	Boolean	Sort order (used only if field specified as string)

Returns: Promise | null -

If sortParamName is set on store, this method returns Promise which is resolved after data is loaded from remote server, otherwise it returns null

clearSorters

Removes all sorters, turning store sorting off.

Returns: Promise | null -

If sortParamName is set on store, this method returns Promise which is resolved after data is loaded from remote server, otherwise it returns null

createSorterFn

Creates a function used with Array#sort when sorting the store. Override to use your own custom sorting logic.

Parameter	Type	Description
`sorters`	Sorter[]	An array of sorter config objects

Returns: function

removeSorter

Remove a sorting level (a sorter)

Parameter	Type	Description
`field`	String \| function	Stop sorting by this field (or sorter function)

Returns: Promise | null -

If sortParamName is set on store, this method returns Promise which is resolved after data is loaded from remote server, otherwise it returns null

sort

Sort records, either by replacing current sorters or by adding to them. A sorter can specify a custom sorting function which will be called with arguments (recordA, recordB). Works in the same way as a standard array sorter, except that returning null triggers the stores normal sorting routine.

// single sorter
store.sort('age');

// single sorter as object, descending order
store.sort({ field : 'age', ascending : false });

// multiple sorters
store.sort(['age', 'name']);

// using custom sorting function
store.sort((recordA, recordB) => {
    // apply custom logic, for example:
    return recordA.name.length < recordB.name.length ? -1 : 1;
});

// using locale specific sort (slow)
store.sort({ field : 'name', useLocaleSort : 'sv-SE' });

Parameter	Type	Description
`field`	String \| Sorter[] \| Sorter \| function	Field to sort by. Can also be an array of sorter config objects, or a sorting function, or a sorter config.
`ascending`	Boolean	Sort order. Applicable when the `field` is a string (if not specified and already sorted by the field, reverts direction), or an object and `ascending` property is not specified for the object. `true` by default. Not applicable when `field` is a function. `ascending` is always `true` in this case.
`add`	Boolean	If `true`, adds a sorter to the sorters collection. Not applicable when `field` is an array. In this case always replaces active sorters.
`silent`	Boolean	Set as true to not fire events. UI will not be informed about the changes.

Returns: Promise | null -

If sortParamName is set on store, this method returns Promise which is resolved after data is loaded from remote server, otherwise it returns null

Events

beforeSort

Fired before sorting

// Adding a listener using the "on" method
storeSort.on('beforeSort', ({ source, sorters, records }) => {

});

Parameter	Type	Description
`source`	Store	This Store
`sorters`	Sorter[]	Sorter configs
`records`	Model[]	Records to sort

sort

Fired after sorting

// Adding a listener using the "on" method
storeSort.on('sort', ({ source, sorters, records }) => {

});

Parameter	Type	Description
`source`	Store	This Store
`sorters`	Sorter[]	Sorter configs
`records`	Model[]	Sorted records

Event handlers

onBeforeSort

Called before sorting

new StoreSort({
    onBeforeSort({ source, sorters, records }) {

    }
});

Parameter	Type	Description
`source`	Store	This Store
`sorters`	Sorter[]	Sorter configs
`records`	Model[]	Records to sort

onSort

Called after sorting

new StoreSort({
    onSort({ source, sorters, records }) {

    }
});

Parameter	Type	Description
`source`	Store	This Store
`sorters`	Sorter[]	Sorter configs
`records`	Model[]	Sorted records

Typedefs

Sorter

An immutable object representing a store sorter.

Parameter	Type	Description
`field`	String	Field name
`fn`	function	A custom sorting function, to be used instead of the "field"
`ascending`	Boolean	`true` to sort ascending, `false` to sort descending