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).

caution

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 will be automatically applied when the Column is row grouped if autoSortGroupedColumns is set to true in General Options (the default) and no defaultGroupSortComparator has been provided in GridOptions

Defining a Custom Sort

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

tip

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.

This allows for a JavaScript function to be provided which will be invoked by AdapTable each time the sort order is required for that column.

note

It is done this way due to the limitation of Predefined Config that all State must be stored in JSON (and therefore as strings), preventing JavaScript functions from being saved here.

caution

As there can be only one Sort Order for a Column, implementations provided here will 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.

Entitlements

Custom Sort Entitlement Rules:

  • Full: Everything is available to the User - Custom Sorts can be created, edited or deleted.

  • Hidden: The function will not be applied

  • ReadOnly: User sort columns that have Custom Sorts in Predefined Config but not edit or delete them, nor add others.

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
getAllCustomSort()Retrieves all Custom Sorts 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

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 where it was, users ended up with multiple 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