Custom Sorting

View as Markdown

Summary

  • Custom Sorting gives a column a bespoke sorting order (replacing AG Grid's default for the column's data type)
  • A Custom Sort can be provided in 2 ways:
    • a list of values in Initial Adaptable State (and manageable in the Settings Panel)
    • a comparer function in customSortOptions.customSortComparers
  • Comparers take precedence over list-based sorts for the same column

Important

  • This page discusses Custom Sorting - providing a non-default sort for a Column
  • For layout column sorting (ColumnSorts), see Sorting

Custom sorting enables Adaptable columns to be given a bespoke sort order.

This will be applied by AdapTable whenever the column is sorted in place of the column's default sort order.

Note

  • Custom Sorts are applied when a Column is sorted in AG Grid in both table and pivot Layouts
  • A Custom Sort can be limited to specific Layouts via Layout Extensions

Custom sorting is useful when the contents of a column are typically ordered in a non-standard way.

Deep Dive

Default Sorting Rules for each Column DataType

For example, a 'Ratings' column can be sorted by rating (i.e. 'AAA', 'AA1' etc) rather than alphabetically (the default for string columns).

A Custom Sort can be one of 2 types:

TypeProvided in
Hard-coded List of valuesCustom Sort Initial State (or via the UI)
Comparer functionCustom Sort Options — invoked by AdapTable each time column is sorted

Caution

  • Only one Custom Sort can be supplied per Column
  • Custom Sort Comparers take precedence over Hard-coded Lists

Defining Custom Sorts

At design time developers can configure both types of Custom Sorts.

Hardcoded Values

Custom Sorts can be provided using a list of values in the Custom Sort section of Initial Adaptable State.

AdapTable will sort the Column according to the order of the supplied values.

Note

  • It is likely the column will contain values that are not included in the custom sort list
  • AdapTable will sort them according to the default alphabetic order
Developer Guide

Defining a Custom Sort with Hardcoded Values

const initialState: InitialState = {
    CustomSort: {
        CustomSorts: [
        {
          Name: 'CustomSort-Rating',
          ColumnId: 'Rating',
          SortedValues: ['AAA', 'AA+', 'AA', 'AA-'], // etc.
        },
    ],
  },
} as InitialState;
1
Add Custom Sorts to Initial Adaptable State

Add a CustomSort section containing an array of CustomSort objects.

2
Provide a Name

Choose a unique name for the Custom Sort

3
Select a Column

Specify the Id of Column which will use the Custom Sort

4
Provide a List of Column Values

Supply an ordered list by which the column will be sorted

Note

Values not provided are sorted using Column's default sort order

Custom Sorts: Values
Fork
  • This demo illustrates 2 Columns that contain Custom Sorts which provide a list of Values (and for each we add a Column Sort to the Layout):
    • License - orders using Other as first cell value
    • Language - orders as 'TypeScript', 'JavaScript', 'HTML'
Loading demo…

Comparer Function

For more complicated scenarios a customSortComparer function can be supplied by developers.

This comparer function will be invoked by AdapTable each time the Column is sorted.

Comparer functions are provided in the customSortComparers property of Custom Sort Options.

customSortComparers

Custom Sort Column Comparer Functions

Hint

  • Unlike with Hardcoded Values the customSortComparer function can be given Column Scope
  • This allows, for example, for a single customSortComparer function to be provided for all Date columns
Developer Guide

Defining a Custom Sort using a CustomSortComparer function

Just a few steps are required to define a Custom Sort Comparer.

In this example, we provide a Comparer which will ignore negatives and sort by absolute value

// Sort numeric columns by absolute value
customSortOptions: {
  customSortComparers: [
    {
      name: 'absolute_sort',
      scope: {
        DataTypes: ['number'],
      },
      comparer: (valA: any, valB: any) => {
        return Math.abs(valB) - Math.abs(valA);
      },
    },
  ],
};
1
Provide the Comparer

Add customSortComparers property to Custom Sort Options

2
Choose a Name

Provide a unique name for the Comparer

3
Specify the Scope

The commonly-used Column Scope object defines where the Custom Sort Comparer will run. It can be:

4
Provide a Comparer function

The function receives 2 cell values (and their containing row nodes)

The evaluation returns -1, 1 or 0 based on comparison being made

Custom Sorts: Functions
Fork
  • This demo contains 3 Columns with Custom Sorts provided via a customSortComparer Function:
    • Issue Change - the customSortComparer negates the numbers to order changes by size (we sort on this by default in the Layout)
    • Name - the customSortComparer orders the column according to the value in the GitHub Stars column
    • Rating - the customSortComparer uses the localeCompare function (so it orders a, A, b, B, c, C etc)
Try It Out
  • Sort on the Name column to see how its sorted according to the GitHub Stars column value
  • Sort on the Rating column to see how the comparer function sorts ignoring case
Loading demo…

Using Custom Sorts

Run-time users can create, edit, delete, share and suspend Custom Sorts.

This is done using the Custom Sort section of the Settings Panel.

Caution

  • The AdapTable UI only deals with List-based Custom Sorts
  • Custom Sort Comparers are design-time objects only and not editable, shareable or suspendable at run-time
UI Step by Step Guide

Using the Custom Sort Wizard