Custom Display Format

Summary

Custom Display Formats can be provided when those provided by AdapTable are insufficient

The Display Format options provided by AdapTable fit the vast majority of real-life use cases.

However, if required, Developers can supply bespoke Custom Display Formatters at design time.

This is done via a 2-stage process:

Defining the Custom Formatter in customDisplayFormatters property in Format Column Options
Referencing the Custom Formatter in Format Column Initial State

customDisplayFormatters

CustomDisplayFormatter[]

Custom Formatters used in Format Column Module

CustomDisplayFormatter[]

This property is used to supplement the Display Formatters provided by AdapTable.

The full definition of the CustomDisplayFormatter[] object is:

Property	Description
handler	Function used to render the Custom Display Format
id	Custom Format Id
label	Custom Format Description
scope	Used by Format Columns wizard to show where Custom Display Format can be applied

Handler Function

As can be seen it includes a handler function which AdapTable invokes when the cell is rendered:

handler: (customDisplayFormatterContext: CustomDisplayFormatterContext) => any;

The function receives a CustomDisplayFormatterContext object which provides details of the cell, column and row (and returns the custom display format). The object definition is:

Property	Description
adaptableColumn	Column where Custom Display Format will apply
cellValue	Non-formatted Cell Value
rowNode	Node where Custom Display Format will apply
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

Using a Custom Display Formatter

A CustomDisplayFormatter is used as follows:

formatColumnOptions: {
  customDisplayFormatters: [
    {
      id: 'bigNumberCustomFormat',
      label: 'Big Number Custom Format',
      scope: {
        DataTypes: ['number'],
      },
      handler: (customDisplayFormatterContext: CustomDisplayFormatterContext) => {
        const cellValue: number = customDisplayFormatterContext.cellValue as number;
        return (cellValue > 10000) ?  cellValue / 1000 + 'K' : cellValue;
      },
    },
  ],
},

would then be referenced in the FormatColumn section of Initial Adaptable State;

FormatColumn: {
  FormatColumns: [
  {
      Name: 'FormatColumn-number-115',
      Scope: {
        DataTypes: ['number'],
      },
      DisplayFormat: {
        Formatter: 'NumberFormatter',
        Options: {
          CustomDisplayFormats: ['bigNumberCustomFormat'],
        },
      },
    },
  ],
},

Hint

Only use these when AdapTable's System Display Formats are insufficient for your use case
You might also find that a Template Display Format provides what you require with less complexity

Each definition includes a handler function which AdapTable invokes when the cell is rendered and which should return the custom display format.

Caution

The scope property in the Custom Formatter tells AdapTable which columns in the UI Wizard should offer the option
The actual wiring up is done using the Scope propery in the relevant Format Column Definition

Column Formatting: Custom Formatter

Fork Fork

This example provides 4 Custom Display Formats - using the CustomDisplayFormatterContext object for evaluation:
- for License column where the word 'License' is removed
- for Created column where we just show the Day of the Week
- for Issue Change column where we replace 0 values with a '-'
- for Gitub Stars column where values over one million display M, over one thousand display 'K', or display normally
Note: We still also use some of the display formats shipped by AdapTable (i.e. Licence is UPPER CASE and Created is italicised)

import {
  AdaptableOptions,
  CustomDisplayFormatterContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Custom Display Formats',
  formatColumnOptions: {
    customDisplayFormatters: [
      // Provide Custom Format for license column
      {
        id: 'licenseCustomFormat',
        label: 'License Format',
        scope: {
          ColumnIds: ['license'],
        },
        handler: (
          customDisplayFormatterContext: CustomDisplayFormatterContext
        ) => {
          const cellValue: string =
            customDisplayFormatterContext.cellValue as string;
          return cellValue.replaceAll('License', '');
        },
      },
      // Provide Custom Format for Issue Change Column
      {
        id: 'weekIssueChangeFormat',
        label: 'Week Change Custom Format',
        scope: {ColumnIds: ['week_issue_change']},
        handler: (
          customDisplayFormatterContext: CustomDisplayFormatterContext
        ) => {
          const currentvalue: any = customDisplayFormatterContext.cellValue;
          return currentvalue === 0 ? '-' : currentvalue;
        },
      },
      // Provide Custom Format for all Date Columns
      {
        id: 'weekDayCustomFormat',
        label: 'Created At Format',
        scope: {DataTypes: ['date']},
        handler: (
          customDisplayFormatterContext: CustomDisplayFormatterContext
        ) => {
          if (
            !customDisplayFormatterContext ||
            !customDisplayFormatterContext.cellValue
          ) {
            return undefined;
          }
          return new Date(
            customDisplayFormatterContext.cellValue
          ).toLocaleString('en-us', {weekday: 'long'});
        },
      },
      // Provide Custom Format for all Numeric Columns
      {
        id: 'hundredThousandFormat',
        label: 'Hundred Thousand Format',
        scope: {DataTypes: ['number']},
        handler: (
          customDisplayFormatterContext: CustomDisplayFormatterContext
        ) => {
          const currentvalue: number = customDisplayFormatterContext.cellValue;
          if (currentvalue > 1000000) {
            return (currentvalue / 1000000).toFixed(2) + 'M';
          }
          if (currentvalue > 1000) {
            return (currentvalue / 1000).toFixed(2) + 'K';
          }
          return currentvalue;
        },
      },
    ],
  },
  initialState: {
    Dashboard: {
      ModuleButtons: ['FormatColumn', 'SettingsPanel'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'language',
            'license',
            'github_stars',
            'closed_issues_count',
            'created_at',
            'closed_pr_count',
            'updated_at',
            'week_issue_change',
            'github_watchers',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
    FormatColumn: {
      FormatColumns: [
        // Wire up the License Custom Format
        {
          Name: 'formatColumn-license',
          Scope: {
            ColumnIds: ['license'],
          },
          DisplayFormat: {
            Formatter: 'StringFormatter',
            Options: {
              CustomDisplayFormats: ['licenseCustomFormat'],
              Case: 'Upper',
            },
          },
        },
        // Wire up the Date Custom Format for Created Column
        {
          Name: 'formatColumn-created_at',
          Scope: {
            ColumnIds: ['created_at'],
          },
          Style: {
            FontStyle: 'Italic',
          },
          DisplayFormat: {
            Formatter: 'DateFormatter',
            Options: {
              CustomDisplayFormats: ['weekDayCustomFormat'],
            },
          },
        },
        // Wire up the Week Issue Change Custom Format
        {
          Name: 'formatColumn-week_issue_change',
          Scope: {ColumnIds: ['week_issue_change']},
          DisplayFormat: {
            Formatter: 'NumberFormatter',
            Options: {CustomDisplayFormats: ['weekIssueChangeFormat']},
          },
        },
        // Wire up the Nueric Custom Format for Github Stars column
        {
          Name: 'formatColumn-github_stars',
          Scope: {ColumnIds: ['github_stars']},
          DisplayFormat: {
            Formatter: 'NumberFormatter',
            Options: {CustomDisplayFormats: ['hundredThousandFormat']},
          },
        },
      ],
    },
  },
};

PreviousTemplate Format NextConfiguring Formatting

Framework: