Custom Sort

The Custom Sort Module enables columns to be given a different sort order to the default for their data type.

This is useful when users need to order a column in an non-standard way (i.e. not in alphabetical, numerical, or date order).

warning

Only one Custom Sort can be supplied per Column.

For example, to sort a 'Moody's Rating' Column according to the rating (i.e. 'Aaa', 'Aa1', 'Aa2', etc) rather than alphabetically a Custom Sort would be used.

important

Custom Sorts are applied both when the Column is sorted both in table view and in pivot view.

tip

Custom Sorts are automatically applied when the Column is row grouped if autoSortGroupedColumns is true in General Options (the default) and no defaultGroupSortComparator was provided in GridOptions

Defining a Custom Sort

A Custom Sort can be provided in one of 2 ways:

caution

If the Column contains values that are not included in either of the above implementations, they are sorted according to the default order for the column.

note

The default sort order for text columns is alphabetical order; for numerical columns it is high-low order; and for date columns it is oldest-newest order.

List of Values

The Custom Sort object in Custom Sort Config contains a SortedValues property: a 'hardcoded' list of column values which will be evaluated according to the list order

important

When a Custom Sort Order based on Sorted Values is used, AdapTable applies the custom order first.

export default {
CustomSort: {
CustomSorts: [
{
ColumnId: 'Rating',
SortedValues: ['AAA', 'AA+', 'AA', 'AA-'], // etc.
},
],
},
} as PredefinedConfig;

Column Sort Comparers

An alternative to a hardcoded list is to provide columnSortComparers in General Options.

These are JavaScript functions which are invoked by AdapTable each time that column is sorted.

note

This is because of the limitation of Predefined Config storing all State as JSON (and therefore as strings), preventing JavaScript functions from being included

caution

As there can be only one Sort Order for a Column, implementations provided here take precedence over those given in Predefined Config

generalOptions = {
columnSortComparers: [
{
columnId: 'country',
comparer: (valueA: any, valueB: any, nodeA?: any, nodeB?: any) => {
if (valueA === 'United Kingdom') {
return -1;
}
if (valueB === 'United Kingdom') {
return 1;
}
return 0;
},
},
{
columnId: 'employee',
comparer: (valueA: any, valueB: any, nodeA?: any, nodeB?: any) => {
if (!valueA || !valueB) {
return 0;
}
const fullName = valueA.split(' ');
const fullNameB = valueB.split(' ');
return fullName[fullName.length - 1] > fullNameB[fullNameB.length - 1]
? 1
: -1;
},
},
],
};

In this example we have provided 2 Column Sort Comparers:

  • On the 'country' column so that it always returns 'United Kingdom' first
  • On the 'employee' column so that it sorts by the employee's surname
tip

AdapTable will try to prevent a new Custom Sort being created for a Column which already has a Column Sort Comparer

UI Elements

Custom Sort includes the following UI Elements:

  • Popup - Shows a list of existing Custom Sorts with Edit and Delete buttons. Plus an Add button to start the Custom Sort Wizard which facilitates the creation and editing of a Custom Sort.

  • Column Menu - The Create Custom Sort Menu Item starts the Custom Sort wizard; if the column already has a Custom Sort it says Edit Custom Sort.

UI Entitlements

UI Entitlements behaviour is as expected for Full and Hidden Access Levels.

The ReadOnly Entitlement behaviour is Custom Sorts will be applied when a Column containing one is sorted, but Users cannot manage or suspend them.

API

The Custom Sort API contains the following methods:

MethodDescription
addCustomSort(customSort)Adds a Custom Sort to Custom Sort collection in Adaptable State
createCustomSort(columnId, values)Creates new Custom Sort based on given values
deleteCustomSort(columnId)Removes Custom Sort for a given ColumnId
editCustomSort(columnId, values)Updates existing Custom Sort with new set of Sorted Values
getAllActiveCustomSort()Retrieves all Custom Sorts that are active (not-suspended) in Adaptable State
getAllCustomSort()Retrieves all Custom Sorts in Adaptable State
getAllSuspendedCustomSort()Retrieves all Custom Sorts that are suspended in Adaptable State
getCustomSortByColumn(columnId)Retrieves Custom Sort from Adaptable State for given ColumnId
getCustomSortState()Retrieves Custom Sort section from Adaptable State
showCustomSortPopup()Opens Custom Sort popup screen
suspendCustomSort(customSort)Suspends Custom Sort
unSuspendCustomSort(customSort)Un-suspends or activates a suspended Custom Sort

FAQ

Not all the values we want to include in the sort are currently in the grid, so they don't appear in the dropdown. Can we add items by hand?

That is not possible because in previous versions of AdapTable where it was allowed, users ended up with multiple differently-spelled variations of the same item.

However there is an option for developers to supply their own list of Permitted Values so the listbox will contain all the items that you will require for your sort - see User Interface Options.

Additionally, if you provide a Custom Sort as part of your Predefined Config then it can contain whichever values you want.

Can we run the Custom Sort when pivoting?

Yes - any column that has a Custom Sort will have it automatically applied if the column is part of a pivot view.

More Information