AdapTable Version:

Framework:

Formatting and Styling Columns in AdapTable

Summary

The Format Column Module enables columns to be given a specific look and feel
This can either always be applied, or when a Condition (either Predicate or Expression) is met
The Format Column can be scoped to one or more Columns or DataTypes, or the
The Format Column can be either:
- a Style to be applied to the Column, which includes Colours, Font Properties and Alignment
- a Display Format for numeric, date and string columns (with presets available)
AdapTable provides rules for Format Column precedence

AdapTable makes it easy for users distinctively to format and / or style Columns (and rows) 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

There are 5 main elements to Column Formatting:

Column Scope - defining which columns or datatypes (or whole row) should be rendered
Column Elements - defining which elements of a Column to render (Cells or Header)
Rendering the Column - using a custom Column Style and / or a bespoke Display Format
Condition - an optional Rule to limit the rendering only to matching columns and cells
Other Settings - e.g. whether to include Grouped and Summary Rows

Note

Column Formatting can be applied to all Columns including Calculated and Free Text Columns
Formatted columns can still be edited (if the column is editable) or filtered (if the column is filterable)

The Style and Display Format are not mutually exclusive.

Hint

A Column Format can include any of a Style or Display Format as required

Column Style

A Format Column will often include a bespoke Column Style.

This will render a bespoke, rich and flexible, set of colours, font properties and alignment settings for the Column (or Row) and leverages the commonly used Adaptable Style object.

Display Formats

A Format Column can also include a Display Format.

This will apply a specific formatter to Number, Date or String Columns.

Hint

Format Columns can include either or both of an Column Style or a Display Format
The AdapTable wizards provides Presets for common Formats as a useful convenvience

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 Column Formatting definition is applied for all the items in Scope.

However, this can be changed by providing an optional Condition.

In this scenario, only the Columns or Rows for which the Condition evaluates as true are formatted.

Find Out More

See Conditional Styling for more information 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

Formatting Tips and Tricks in AdapTable

(Recorded with AdapTable v16.2)

AdapTable Resources

NextStyles

Framework:

Formatting and Styling Columns in AdapTable

Summary

Note

Note

Hint

Column Style

Display Formats

Hint

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

Formatting Tips and Tricks in AdapTable

AdapTable Resources