AdapTable Version:

Framework:

Sorting

Summary

Column Sorting in AdapTable is configured through Layouts which contain full sorting information
Additionaly AdapTable offers Custom Sorting whereby a bespoke sort order can be provided for a Column
Custom Sorts can be supplied in 2 ways:
- as a hard coded list in Initial Adaptable State
- a function supplied in Adaptable Options

AdapTable fully supports sorting of your data in AG Grid.

Column Sorting

Column Sorting is managed through Layouts Sorting.

Each Layout includes a ColumnSorts which contains details of which Columns are sorted and in which order.

Hint

Like all Layout props this can be predefined, allowing developers to define the sorted columns when the Layout loads

Custom 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

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

Deep Dive

Default Sorting Rules for each Column DataType

The default sort order in AG Grid for each data type is:

Column Data Type	Rule
String	Alphabetical Order
Number	Highest to Lowest
Date	Oldest to Newest

This is what is used when a Column is sorted in the absence of Custom Sorting

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:

Hard-coded List of Values - provided in Custom Sort Initial State (or via the UI)
Comparer function - provided in Custom Sort Options, invoked by AdapTable each time the column's 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

Its likely the Column will contain values that are not included in the Custom Sort implementation 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;

Add Custom Sorts to Initial Adaptable State

Add a CustomSort section containing an array of CustomSort objects.

Provide a Name

Choose a unique name for the Custom Sort

Select a Column

Specify the Id of Column which will use the Custom Sort

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 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'

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

ColumnValuesComparer[]

Custom Sort Column Comparer Functions

ColumnValuesComparer[]

Functions used to compare Columns whem implementing Custom Sort.

Caution

As there can be only one Sort Order for a Column, implementations provided here take precedence over those given as a hardcoded list in Initial Adaptable State

The function returns a ColumnValuesComparer object which is defined as follows:

Property	Description
comparer	Comparer function to use
name	Name of the CustomSort Comparer
scope	Column for which to compare values

The scope property is of type ColumnScope which is commonly used across AdapTable.

The comparer property is of type AdaptableComparerFunction which is defined as follows:

/**
 * Standard comparer function used to evaluate custom sorts
 * should return -1, 0, 1 as required
 * valueA and valueB are first and second cell to compare
 * nodeA and nodeB are first and second rows to compare
 */
export type AdaptableComparerFunction = (
  valueA: any,
  valueB: any,
  nodeA: IRowNode,
  nodeB: IRowNode
) => number;

The Comparer can be used like this:

// Compare Issue Change by size of change (ignoring negatives)
const adaptableOptions: AdaptableOptions = {
    customSortOptions : {
        customSortComparers: [
        {
            name: 'absolute_custom_sort',
            scope: { ColumnIds: ['week_issue_change'] },
            comparer: (valueA: any, valueB: any, nodeA?: IRowNode, nodeB?: IRowNode) => {
                return Math.abs(valueB) - Math.abs(valueA);
            },
        }:
      ],
    };
};

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 Issue Change by size of change (ignoring negatives)
customSortOptions : {
  customSortComparers: [
  {
    name: 'absolute_sort',
    scope: { 
        DataTypes: ['number'] 
    },
    comparer: (valA: any, valB: any: IRowNode) 
      => { return Math.abs(valB) - Math.abs(valA);
    },
  }:
  ]
};

Provide the Comparer

Add customSortComparers property to Custom Sort Options

Choose a Name

Provide a unique name for the Comparer

Specify the Scope

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

One or more ColumnIds
A Cell Data Type (e.g. text, date, number)
A Column Type

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

import {AdaptableOptions} from '@adaptabletools/adaptable';
import {IRowNode} from 'ag-grid-enterprise';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Custom Sort Functions',
  customSortOptions: {
    customSortComparers: [
      {
        name: 'absolute_sort',
        scope: {
          ColumnIds: ['week_issue_change'],
        },
        comparer: (valueA: any, valueB: any) => {
          return Math.abs(valueB) - Math.abs(valueA);
        },
      },
      {
        name: 'rating_sort',
        scope: {
          ColumnIds: ['rating'],
        },
        comparer: (valueA: any, valueB: any) => {
          return valueA.localeCompare(valueB);
        },
      },
      {
        name: 'name_sort',
        scope: {
          ColumnIds: ['name'],
        },
        comparer: (
          valueA: any,
          valueB: any,
          nodeA: IRowNode | undefined,
          nodeB: IRowNode | undefined
        ) => {
          const nodeAGitHubStars = nodeA?.data['github_stars'];
          const nodeBGitHubStars = nodeB?.data['github_stars'];
          if (nodeAGitHubStars > nodeBGitHubStars) {
            return -1;
          }
          if (nodeAGitHubStars < nodeBGitHubStars) {
            return 1;
          }
          return 0;
        },
      },
    ],
  },

  initialState: {
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          ColumnSorts: [
            {
              ColumnId: 'week_issue_change',
              SortOrder: 'Asc',
            },
          ],
          TableColumns: [
            'name',
            'github_stars',
            'rating',
            'week_issue_change',
            'license',
            'language',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'open_issues_count',
            'open_pr_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Using Custom Sorts

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

This is doing 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

Creating an Absolute Sort

(Recorded with AdapTable v15.0)

PreviousTechnical Reference NextTechnical Reference

Framework: