Custom Sort

The Custom Sort Function 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 Rating column according to the rating (i.e. 'AAA', 'AA' etc) rather than alphabetically a Custom Sort would be used.

tip

Custom Sorts will be applied both when you sort the Column in table view and in pivot view.

Defining a Custom Sort

The Custom Sort section of Predefined Config can accept 2 types of Custom Sort definitions:

  • SortedValues - a 'hardcoded' list of column values which will be evaluated according to the list order

  • CustomSortComparerFunction - a standard 'Comparer' function which will be evaluated each time sort is applied (see below).

Custom Sort Values

important

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

tip

If the column contains values that are not included in the custom sort definition, 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.

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

Custom Sort Comparer Function

An alternative to a hardcoded list is to provide an implementation of the CustomSortComparerFunction.

As with all instances where a JavaScript function needs to be provided to AdapTable, this is done in 2 steps:

note

Predefined Config is stored as JSON so cannot include JavaScript functions (as they cannot be stringifed)

  1. Provide a custom, named CustomSortComparerFunction implementation in the User Functions section of Adaptable Options.

  2. Reference that function by name in the Custom Sort section of Predefined Config.

// Predefined Config
export default {
CustomSort: {
CustomSorts: [
{
ColumnId: 'country',
CustomSortComparerFunction: 'countryComparer',
},
{
ColumnId: 'employee',
CustomSortComparerFunction: 'employeeComparer',
},
],
},
} as PredefinedConfig;
// Adaptable Options
const adaptableOptions: AdaptableOptions = {
userFunctions: [
{
name: 'countryComparer',
type: 'CustomSortComparerFunction',
handler(valueA: any, valueB: any, nodeA?: any, nodeB?: any) {
if (valueA === 'United Kingdom') {
return -1;
}
if (valueB === 'United Kingdom') {
return 1;
}
return 0;
},
},
{
name: 'employeeComparer',
type: 'CustomSortComparerFunction',
handler(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 created 2 Custom Sorts Comparer Functions:

  • 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

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 inputted 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 dont 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 Items so the listbox will contain all the items that you will require for your sort - see User Interface State.

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