AdapTable Version:

Framework:

Configuring Column Formatting

Summary

Developers provide Format Columns Styles, Display Formats and Conditions through Initial Adaptable State
These include a property which stipulates whether the Format is applied in Grouped Rows

Defining

Column Formatting can be provided at design-time through Format Column Initial State

This will ensure that all styles and display formats are applied when the Application first loads, and that any changes will be stored with Adaptable State.

Multiple Format Columns

It can be the case that several Format Column objects can all be scoped (i.e. be relevant) for the same grid cell.

When this happens all the Format Columns object are composed into a single Format Column.

AdapTable will merge all the Style properties into a single Adaptable Style object which will then be rendered.

Caution

The order in which the Format Columns are defined - either in Initial Adaptable State or the UI - is important
AdapTable has strict rules about precedence - see the section below for more information

Column Formatting Composition

Fork Fork

This example demonstrates how Format Columns are composed. We provide 4 Format Columns:
- All Columns are Centre Aligned
- Numeric Columns are Light Green
- 3 Columns - Github Stars, Issue Change and Github Watchers - are Bold and Italic
- The Github Stars Column has both a Prefix and a Suffix of '***' but with Condition of > 20,000
Note how each Columns display all the formats which are relevant to it, and the Github Stars column shows all 4 Formats

Expand to see the Format Column Definitions

FormatColumn: {
  FormatColumns: [
    {
      Name: 'FormatColumn-all-101',
      Scope: {
        All: true,
      },
      Style: {
        Alignment: 'Center',
      },
    },
    {
      Name: 'FormatColumn-number-102',
      Scope: {
        DataTypes: ['number'],
      },
      Style: {
        ForeColor: 'LightGreen',
      },
    },
    {
      Name: 'FormatColumn-github_stars-103',
      Scope: {
        ColumnIds: ['github_stars', 'week_issue_change', 'github_watchers'],
      },
      Style: {
        FontWeight: 'Bold',
        FontStyle: 'Italic'
      },
    },
    {
      Name: 'FormatColumn-github_stars-104',
      Scope: {
        ColumnIds: ['github_stars'],
      },
      DisplayFormat: {
        Formatter: 'NumberFormatter',
        Options: {
          Prefix: '***',
          Suffix: '***',
        },
      },
      Rule: {
        Predicates: [
          {
            PredicateId: 'GreaterThan',
            Inputs: ['20000'],
          },
        ],
      },
    },
  ],
},

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Format Column Composition',
  initialState: {
    Dashboard: {
      ModuleButtons: ['FormatColumn', 'SettingsPanel'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'github_stars',
            'week_issue_change',
            'github_watchers',
            'closed_issues_count',
            'created_at',
            'closed_pr_count',
            'license',
            'language',
            'updated_at',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'style-all',
          Scope: {
            All: true,
          },
          Style: {
            Alignment: 'Center',
          },
        },
        {
          Name: 'formatColumn-number',
          Scope: {
            DataTypes: ['number'],
          },
          Style: {
            ForeColor: 'LightGreen',
          },
        },
        {
          Name: 'formatColumn-github_stars',
          Scope: {
            ColumnIds: ['github_stars', 'week_issue_change', 'github_watchers'],
          },
          Style: {
            FontWeight: 'Bold',
            FontStyle: 'Italic',
          },
        },
        {
          Name: 'formatColumn-github_stars',
          Scope: {
            ColumnIds: ['github_stars'],
          },
          DisplayFormat: {
            Formatter: 'NumberFormatter',
            Options: {
              Prefix: '***',
              Suffix: '***',
            },
          },
          Rule: {
            Predicates: [
              {
                PredicateId: 'GreaterThan',
                Inputs: ['20000'],
              },
            ],
          },
        },
      ],
    },
  },
};

Format Column Precedence

As noted above, multiple Format Columns are merged into a single Adaptable Style object.

However its important to note that Format Columns are evaluated in their precedence order.

This means that if several Format Columns define the same style property (e.g. background color, font size, etc.), the Format Column with the highest precedence wins.

Caution

Overlapping Display Formats are NOT merged - the one with the higher Precedence is displayed

AdapTable sets precedence purely on the order of the definitions in the Format Column Initial State.

Each element listed in the State has higher precedence than the next.

Note

Precedence Rules are used not just for Styles and Display Format but also General Settings (e.g. Cell Alignment)

The Precedence order can be changed at runtime in 2 ways:

using the UI buttons (up & down arrows) in the Format Column Setttings Panel
programmatically using the increment & decrement API methods in Format Column API

Hint

It is important that Format Columns with more specific conditions have a higher priority order
Otherwise they would be overridden by more general Format Columns

Column Formatting Precedence Order

Fork Fork

This (slightly contrived) example provides 4 Display Format with various different and overlapping Scopes, Styles and DisplayFormats:

for all numeric columns with values greater than 1 million are divided by 1.000.000 and suffixed with 'M'
for all numeric columns with values greater than 1 thousand are divided by 1.000 and suffixed with 'K'
columns github_stars,open_issues_count,open_pr_count are displayed with a custom background color
all columns with the condition that the license is NOT 'MIT' are displayed with custom background, foreground, border and font style

Note: their definition (and implicitly precedence) order is determinant for the final formatting

Try It Out

Increment/decrement the precedence order of each Format Column and check how the resulting formatting changes
Suspend one or several Format Columns and check the resulting formatting

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Format Column Precedence',
  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: [
        {
          Name: 'formatColumn-number',
          Scope: {
            DataTypes: ['number'],
          },
          Style: {
            BackColor: '#ffffe0',
            FontWeight: 'Bold',
            ForeColor: 'Purple',
          },
          DisplayFormat: {
            Formatter: 'NumberFormatter',
            Options: {
              Suffix: 'M',
              Multiplier: 0.000001,
            },
          },
          Rule: {
            Predicates: [
              {
                PredicateId: 'GreaterThan',
                Inputs: ['1000000'],
              },
            ],
          },
        },
        {
          Name: 'formatColumn-number',
          Scope: {
            DataTypes: ['number'],
          },
          DisplayFormat: {
            Formatter: 'NumberFormatter',
            Options: {
              Suffix: 'K',
              Multiplier: 0.001,
            },
          },
          Rule: {
            Predicates: [
              {
                PredicateId: 'GreaterThan',
                Inputs: ['1000'],
              },
            ],
          },
        },
        {
          Name: 'formatColumn-open_pr_count',
          Scope: {
            ColumnIds: ['open_pr_count', 'github_stars', 'open_issues_count'],
          },
          Style: {
            BackColor: '#c2eef5',
            ForeColor: 'Red',
          },
        },
        {
          Name: 'style-all',
          Scope: {
            All: true,
          },
          Style: {
            BackColor: '#a8ffe5',
            ForeColor: '#b10202',
            BorderColor: '#f24040',
            FontStyle: 'Italic',
          },
          Rule: {
            BooleanExpression: `[license] != 'MIT License'`,
          },
        },
      ],
    },
  },
};

Excluding Certain Rows

By default Column Formatting is automatically applied to all Rows - including Grouped, Summary and Total Rows.

Note

The Format Column is only applied in Grouped and Total Rows to Columns which have an Aggregation set

This behaviour can be changed by configuring the RowScope property when defining the Format Column.

The RowScope object enables 4 types of rows to be excluded from the Format Column:

Data Rows
Grouped Rows
Summary Rows
Grand Total Rows

Hint

Use the ExcludeDataRows option to create a Format Column that is only rendered in a Group Row

Column Formatting - Excluding Rows

Fork Fork

This Example has 3 Format Columns - with different configurations for Grouped Rows and Data Rows:
- Github Stars has a Style (with fore and back colours and italicised) - with Grouped Rows excluded
- Closed Issues is Blue and has a Cell Alignment of Center - with Grouped Rows included
- Open PRs is Bold and yellow - with Grouped Rows included but Data Rows excluded

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Formatting Grouped Rows',
  initialState: {
    Dashboard: {
      ModuleButtons: ['FormatColumn', 'SettingsPanel'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'github_stars',
            'closed_issues_count',
            'open_pr_count',
            'created_at',
            'license',
            'updated_at',
            'pushed_at',
            'has_projects',
            'has_wiki',
          ],
          RowGroupedColumns: ['language'],
          TableAggregationColumns: [
            {
              ColumnId: 'closed_issues_count',
              AggFunc: 'max',
            },
            {
              ColumnId: 'github_stars',
              AggFunc: 'sum',
            },
            {
              ColumnId: 'open_pr_count',
              AggFunc: 'avg',
            },
          ],
          RowGroupValues: {
            RowGroupDefaultBehavior: 'collapsed',
            GroupKeys: [
              {
                RowGroupedColumns: ['language'],
                ExceptionGroupKeys: [['HTML']],
              },
            ],
          },
          AutoSizeColumns: true,
        },
      ],
    },
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'formatColumn-github_stars',
          Scope: {
            ColumnIds: ['github_stars'],
          },
          Style: {
            ForeColor: '#c2bb00',
            BackColor: '#f5f5f5',
            FontStyle: 'Italic',
          },
          RowScope: {
            ExcludeGroupRows: true,
          },
        },
        {
          Name: 'formatColumn-closed_issues_count',
          Scope: {
            ColumnIds: ['closed_issues_count'],
          },
          Style: {
            ForeColor: 'LightBlue',
            Alignment: 'Center',
          },
        },
        {
          Name: 'formatColumn-open_pr_count',
          Scope: {
            ColumnIds: ['open_pr_count'],
          },
          Style: {
            ForeColor: 'Yellow',
            FontWeight: 'Bold',
          },
          RowScope: {
            ExcludeDataRows: true,
          },
        },
      ],
    },
  },
};

Excluding Column Groups

By default Column Formatting is automatically to Columns which are inside Column Groups.

However it is possible to apply the formatting only if the containing Column Group is expanded or collapsed.

This is done using the ColumnGroupScope property in the Format Column object which can take 3 values:

Both (the default)
Expanded
Collapsed

Find Out More

See Formatting Column Groups for more details and a demo

PreviousCustom Format NextColumn Headers

Framework: