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).
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.
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
When a Custom Sort Order based on Sorted Values is used, AdapTable applies the custom order first.
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.
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.
Custom Sort Comparer Function
An alternative to a hardcoded list is to provide an implementation of the CustomSortComparerFunction.
Provide a custom, named CustomSortComparerFunction implementation in the User Functions section of Adaptable Options.
Reference that function by name in the Custom Sort section of Predefined Config.
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
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.
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.
The Custom Sort API contains the following methods:
|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|
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.