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).
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.
Custom Sorts are applied both when the Column is sorted both in table view and in pivot view.
Defining a Custom Sort
A Custom Sort can be provided in one of 2 ways:
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.
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
When a Custom Sort Order based on Sorted Values is used, AdapTable applies the custom order first.
Column Sort Comparers
An alternative to a hardcoded list is to provide
columnSortComparers in General Options.
As there can be only one Sort Order for a Column, implementations provided here take precedence over those given in Predefined Config
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
AdapTable will try to prevent a new Custom Sort being created for a Column which already has a Column Sort Comparer
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.
The ReadOnly Entitlement behaviour is Custom Sorts will be applied when a Column containing one is sorted, but Users cannot manage or suspend them.
The Custom Sort API contains the following methods:
|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|
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.