Format Columns

Summary

The Format Column module controls how column values read and how cells look in AG Grid
Each definition can include a Display Format, an Style, or both
Definitions are scoped to columns, data types, or whole rows; an optional Condition limits when a rule applies
Multiple Format Columns can apply to the same column; AdapTable resolves precedence automatically

The Format Column module lets users control how values read and how cells look in AG Grid.

Note

AdapTable also provides a comprehensive Theming Module
That is used to theme the AdapTable UI (i.e. all wizards and popups) rather than AG Grid Columns, Rows & Cells

Each Format Column definition shares the same building blocks:

Scope — which columns, data types, or whole rows are in scope (see Scope below)
Target — cell or column header
Display Format and/or Style — how values read and how cells look (not mutually exclusive)
Condition — optional rule; most often used with styles (see Conditional Styling)
Row scope — data rows, group rows, summaries, and related settings

Note

Format Columns apply to all column types including Calculated and Free Text columns
Formatted columns remain editable and filterable when those features are enabled on the column

Find Out More

Display Formats — numeric, date, string, and custom value formatters (presets included)
Styles — colours, fonts, alignment, and optional CSS classes
Conditional Styling — predicate and expression rules (under Styles in the sidebar)

Column Formatting

Fork Fork

This example contains a mixture of different Column Formats and Styles:
- Name has an Adaptable Style of Bold
- Github Stars has a Display Format (showing a Prefix) and Adaptable Style for both fore and back colours
- All Date columns have a Display Format of 'MMM do yyyy' applied
- A Blue Style has been set for the Whole Row, using a Condition: [language] = "TypeScript" AND [license] = "MIT License"

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Formatting Columns',
  initialState: {
    Dashboard: {
      ModuleButtons: ['FormatColumn', 'SettingsPanel'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'FormatColumn',
      Layouts: [
        {
          Name: 'FormatColumn',
          TableColumns: [
            'name',
            'github_stars',
            'has_projects',
            'language',
            'closed_issues_count',
            'created_at',
            'license',
            'open_pr_count',
            'updated_at',
            'pushed_at',
            'has_wiki',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'formatColumn-name',
          Scope: {
            ColumnIds: ['name'],
          },
          Style: {
            FontWeight: 'Bold',
          },
        },
        {
          Name: 'formatColumn-github_stars',
          Scope: {
            ColumnIds: ['github_stars'],
          },
          Style: {
            ForeColor: '#c2bb00',
            BackColor: '#f5f5f5',
          },
          DisplayFormat: {
            Formatter: 'NumberFormatter',
            Options: {
              Prefix: 'Stars: ',
            },
          },
        },
        {
          Name: 'formatColumn-date',
          Scope: {
            DataTypes: ['date'],
          },
          DisplayFormat: {
            Formatter: 'DateFormatter',
            Options: {
              Pattern: 'MMM do yyyy',
            },
          },
          Style: {
            Alignment: 'Center',
          },
        },
        {
          Name: 'style-all',
          Style: {
            BackColor: '#00ffff',
            ForeColor: 'Black',
          },
          Scope: {
            All: true,
          },
          Rule: {
            BooleanExpression:
              '[language] = "TypeScript" AND [license] = "MIT License"  ',
          },
        },
      ],
    },
  },
};

The style specified in Column Formatting has the lowest level of precedence when AdapTable applies styling.

Deep Dive

Style Precedence in AdapTable

Scope

Scope defines where the Format Column is applied.

Scope is provided by the commonly-used Column Scope Object which provides 4 sets of options:

All Columns - The entire Row can be be rendered with a Format Column (by providing a Scope of 'All')
Columns - consists of a list of Column Names which will display the Style
Column Types - applies style to all Columns share supplied Column Type
Data Types - applies style to all Columns which share supplied Cell Data Type (e.g. text, number or date)

Hint

Use this to give all dates a distinctive format, or apply a condition to all numbers, e.g. Green Positive / Red Negative

Format Column - Scope

Fork Fork

This demo showcases how to use Scope in Format Columns
- The Issue Change Column has 2 Format Conditions applied (Green for Positive and Red for Negative)
- All Columns of DataType Date have a Display Format (of 'MMM do yyyy')
- Columns with a ColumnType of 'Github' (i.e. Github Watchers & Github Stars) are italicised and centre-aligned
- Whole Rows are styled with match an Expression ('[language] = "TypeScript" AND [license] = "MIT License" ')

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Format Column Scope',
  columnOptions: {
    columnTypes: ['github', 'issue-pr'],
  },
  initialState: {
    Dashboard: {ModuleButtons: ['FormatColumn', 'SettingsPanel']},
    Theme: {CurrentTheme: 'dark'},
    FormatColumn: {
      FormatColumns: [
        // Column Scope
        {
          Name: 'formatColumn-week_issue_change',
          Style: {
            ForeColor: 'Green',
          },
          Scope: {
            ColumnIds: ['week_issue_change'],
          },
          Rule: {
            Predicates: [
              {
                PredicateId: 'Positive',
              },
            ],
          },
        },
        {
          Name: 'formatColumn-week_issue_change',
          Style: {
            ForeColor: 'Red',
          },
          Scope: {
            ColumnIds: ['week_issue_change'],
          },
          Rule: {
            Predicates: [
              {
                PredicateId: 'Negative',
              },
            ],
          },
        },

        // DataType Scope
        {
          Name: 'formatColumn-date',
          Scope: {
            DataTypes: ['date'],
          },
          DisplayFormat: {
            Formatter: 'DateFormatter',
            Options: {
              Pattern: 'MMM do yyyy',
            },
          },
        },

        // ColumnType Scope
        {
          Name: 'formatColumn-github',
          Scope: {
            ColumnTypes: ['github'],
          },
          Style: {
            FontStyle: 'Italic',
            Alignment: 'Center',
          },
        },

        // Row Scope
        {
          Name: 'style-all',
          Style: {
            BackColor: '#8fd3fe',
            ForeColor: 'Black',
          },
          Scope: {
            All: true,
          },
          Rule: {
            BooleanExpression:
              '[language] = "TypeScript" AND [license] = "MIT License"  ',
          },
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'license',
            'language',
            'week_issue_change',
            'github_watchers',
            'github_stars',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'open_issues_count',
            'open_pr_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Composition & Precedence

Each Column will render every Format Column for which it is in Scope. This means that a Column can successfully display 2 (or more) Format Columns.

Note

If a Column is in scope for 2 clashing Format Columns, AdapTable renders the Format Column with higher precedence

Find Out More

See Configuring Formatting for further details on composition and precedence

Condition

By default, a Format Column applies to every cell in scope. An optional Rule limits application to matching rows — commonly for conditional highlighting (e.g. negative P&L, limit breaches). The same Rule mechanism can also gate a Display Format, though that is less common.

Find Out More

See Conditional Styling for predicates, expressions, and demos

Using Column Formats

Run-time users are able to add, edit, share, suspend and delete Format Columns using the relevant section in the Settings Panel.

Note

There are not Toolbars or Tool Panels for Format Columns

A Menu Item in the Column Menu opens the relevant Wizard.

Hint

When Creating Format Columns the Create Format Column menu item appears in every Column Menu
When Editing each existing Format Column has an Edit Format Column Column Menu Item

The Format Column Wizard enables creating and editing Format Columns.

UI Step by Step Guide

Using the Format Column Wizard

AG Grid Rendering

AG Grid provides very powerful, custom column display functionality, using a combination of Value Getters, Value Formatters and Cell Components (previously called Cell Renderers)

All of these will work in AdapTable and nothing will be lost.

However despite the richness of the AG Grid rendering capabilities we recommend not using AG Grid's Value Formatters or Cell Components, if possible, and instead to use AdapTable's Styling and Formatting features.

Find Out More

See the Tutorial on AG Grid Cell Rendering for more information and examples

UI Entitlements

The UI Entitlements behaviour for Format Columns is as expected for Full and Hidden Access Levels.

The ReadOnly Entitlement behaviour is that the Columns will still be rendered but Users are not permitted to manage or suspend the Format Column definitions.

FAQ

Can I apply more than one Format to a column? Yes, a Column can have as many Format Columns as you require. AdapTable will evaluate and render them in the order they are provided.

Can I use Format Column to display a different caption for the Column? Yes, you can format a Column Header including providing a custom Caption. But it is preferable to do this by using the ColumnHeaders property in a Layout

Why is the Style or Format not being applied in Aggregated values? Check that you have not set ExludeGroupedRows to true in the RowScope property in the Format Column Definition

AdapTable Resources

NextDisplay Formats

Format Columns

Summary

Note

Note

Find Out More

Deep Dive

Style Precedence in AdapTable

Scope

Hint

Composition & Precedence

Note

Find Out More

Condition

Find Out More

Using Column Formats

Note

Hint

UI Step by Step Guide

Using the Format Column Wizard

Find Out More

Note

Find Out More

Caution

AG Grid Rendering

Find Out More

UI Entitlements

FAQ

AdapTable Resources