Managing AG Grid Column Defs at RunTime

Summary

AdapTable helps developers manage AG Grid Column Definitions easily and safely updated at runtime
Two convenience functions reduce the update's complexity while ensuring AdapTable's Layouts work smoothly
Other functions enable Column Definitions to be safely addded and removed at runtime

AG Grid's Column Definitions are immutable.

Nevertheless, AG Grid still makes it possible, at runtime, to add, update or delete ColDefs.

AdapTable supports this functionality via bespoke "wrapper" functions to ensure everything hangs together.

These functions ensure that AG Grid columns are added, updated or deleted correctly, while also ensuring AdapTable's Layouts and other features to run smoothly.

Caution

We strongly recommend you use AdapTable's API functions (listed below) when managing AG Grid columns
AdapTable will invoke the related AG Grid function, but in a way that ensures everything hangs together properly

Updating ColDefs

AG Grid distinguishes betweeen 2 types of Column properties - stateful and non-stateful.

It provides 2 complementary sets of GridAPI functions to update column props based on this distinction:

For the reduced set of "stateful" Column properties the AG Grid Column State API is recommended
For all other Column properties AG Grid's Grid API should be used

AdapTable fully supports AG Grid Column immutability, and also how columns can be updated at run-time.

AdapTable's Grid API contains 2 sets of complementary functions to mirror those provided by AG Grid.

Note

AdapTable provides 2 different sets of methods for stateful and non-stateful Column properties
However the shape of the object that is passsed into each function is identical

Stateful Properties

As noted above, AG Grid defines a subset of column properties as Column State.

These are properties which can be updated without needing to provide a full new set of Column definitions.

AdapTable provides the updateAgGridColumnState function in GridApi to update the Column State for a Column in a safe way.

Hint

A parallel updateAgGridColumnStates function can be used to update the Column State for multiple columns

updateAgGridColumnState

ColumnState

void

Updates the Column State for a given Column

The function take an AG Grid Column State object (of type ColumnState) and returns void.

You should pass in an object that contains the colId of the column and whichever stateful property (or properties) you want to change:

// Hide the Rating column
adaptableApi.gridApi.updateAgGridColumnState({
  colId: 'rating',
  hide: true,
});

The function will, in turn, call AG Grid's applyColumnState function in AG Grid Api in a managed way.

Updating Stateful Column Props at Runtime

Fork Fork

In this demo a Custom Dashboard Toolbar contains 3 buttons that each update stateful AG Grid Column props using the updateAgGridColumnState function:
- The Name column is widened using width
- The Langague column is hidden using hide
- The Github Stars column is sorted and pinned using sort and pin

Expand to see how the Column Definitions are updated

context.adaptableApi.gridApi.updateAgGridColumnState({
  colId: 'name',
  width: 300,
});

context.adaptableApi.gridApi.updateAgGridColumnState({
  colId: 'language',
  hide: true,
});

context.adaptableApi.gridApi.updateAgGridColumnState({
  colId: 'github_stars',
  pinned: 'right',
  sort: 'asc',
});

Try It Out

Click each button in turn and see how they update

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Updating Stateful Column Defs',
  dashboardOptions: {
    customToolbars: [
      {
        name: 'Custom Buttons',
        toolbarButtons: [
          {
            label: 'Widen Name Column',
            buttonStyle: {
              tone: 'info',
              variant: 'outlined',
            },
            onClick: (
              _button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.gridApi.updateAgGridColumnState({
                colId: 'name',
                width: 300,
              });
            },
          },
          {
            label: 'Hide Language Column',
            buttonStyle: {
              tone: 'success',
              variant: 'outlined',
            },
            onClick: (
              _button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.gridApi.updateAgGridColumnState({
                colId: 'language',
                hide: true,
              });
            },
          },
          {
            label: 'Sort & Right-Pin Github Stars Column',
            buttonStyle: {
              tone: 'warning',
              variant: 'outlined',
            },
            onClick: (
              _button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.gridApi.updateAgGridColumnState({
                colId: 'github_stars',
                pinned: 'right',
                sort: 'asc',
              });
            },
          },
        ],
      },
    ],
  },
  initialState: {
    Dashboard: {
      PinnedToolbars: ['Custom Buttons'],
    },
    Theme: {CurrentTheme: 'dark'},
    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,
        },
      ],
    },
  },
};

Non-Stateful Properties

Adaptable also fully supports updating Column properties which are not stateful.

This is done using the updateAgGridColumnDefinition function in GridApi.

updateAgGridColumnDefinition

ColDefWithId

void

Updates non-stateful properties in an AG Grid Column

The function take a ColDefWithId object and returns void.

The ColDefWithId object is essentially an AG Grid Column Definition with a mandatory coldId property.

To use the function, you need to pass in an object that contains the colId of the column and whichever non-stateful property (or properties) you want to change:

// Change the type and editable properties of the Rating column
adaptableApi.gridApi.updateAgGridColumnDefinition({
  colId: 'rating',
  type: ['newCustomType'],
  editable: true
});

Updating Other Column Props at Runtime

Fork Fork

In this example the Custom Dashboard Toolbar again contains 3 buttons that each updates a Column Definition property
But as these are non-stateful AG Grid Column props, the updateAgGridColumnDefinition function is used:
- The Name column is given a new headerName of 'Framework'
- The License column has editable set to true
- The Issue Change column is given a Column Type of 'Github' (because an existing Format Column has a Scope of that Column Type, the Issue Change Column is automatically styled)

Expand to see how the Column Definitions are updated

context.adaptableApi.gridApi.updateAgGridColumnDefinition({
  colId: 'name',
  headerName: 'Framework',
});

context.adaptableApi.gridApi.updateAgGridColumnDefinition({
  colId: 'license',
  editable: true,
});

context.adaptableApi.gridApi.updateAgGridColumnDefinition({
  colId: 'week_issue_change',
  type: ['github'],
});

Try It Out

Click each button in turn and see how they update

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Updating Non Stateful Column Defs',
  columnOptions: {
    columnTypes: ['github'],
  },
  dashboardOptions: {
    customToolbars: [
      {
        name: 'Custom Buttons',
        toolbarButtons: [
          {
            label: 'Change Name Column Header',
            buttonStyle: {
              tone: 'info',
              variant: 'outlined',
            },
            onClick: (
              _button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.gridApi.updateAgGridColumnDefinition({
                colId: 'name',
                headerName: 'Framework',
              });
            },
          },
          {
            label: 'Make License Editable',
            buttonStyle: {
              tone: 'success',
              variant: 'outlined',
            },
            onClick: (
              _button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.gridApi.updateAgGridColumnDefinition({
                colId: 'license',
                editable: true,
              });
            },
          },
          {
            label: 'Change Issue Change Style',
            buttonStyle: {
              tone: 'warning',
              variant: 'outlined',
            },
            onClick: (
              _button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.gridApi.updateAgGridColumnDefinition({
                colId: 'week_issue_change',
                type: ['github'],
                cellDataType: 'number',
              });
            },
          },
        ],
      },
    ],
  },
  initialState: {
    Dashboard: {
      PinnedToolbars: ['Custom Buttons'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'week_issue_change',
            'github_watchers',
            'github_stars',
            '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,
        },
      ],
    },
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'formatColumn-github',
          Scope: {
            ColumnTypes: ['github'],
          },
          Style: {
            ForeColor: 'LightBlue',
            FontWeight: 'Bold',
            Alignment: 'Center',
          },
        },
      ],
    },
  },
};

Adding & Removing ColDefs

AdapTable's GridApi contains 3 functions to safely add and remove AG Grid Column Definitions at run-time:

addAgGridColumnDefinition - adds one ColumnDef
removeAgGridColumnDefinition - removes one ColumnDef
setAgGridColumnDefinitions - adds a group of ColumnDefs

Important

Always use these function when adding new Columns, or removing existing Columns, at runtime
AdapTable will make sure to add or remove column in ColumnDefs correctly and ensure everything works

Adding ColDefs

The addAgGridColumnDefinition function enables a new AG Grid Column Definition to be added at run-time.

addAgGridColumnDefinition

ColDefWithId

void

Adds new AG Grid Columns

The function take a ColDefWithId object and returns void.

The ColDefWithId object is essentially an AG Grid Column Definition with a mandatory coldId property.

To use the function, you need to pass in an object that contains the colId of the column and whichever properties you want the Column to have:

// Provide a Rating column
adaptableApi.gridApi.addAgGridColumnDefinition({
  colId: 'rating',
  field: 'fitch',
  width: 200,
  editable: false,
  cellDataType: 'text'
});

Adding Column Definitions at Runtime

Fork Fork

In this example we provide a button that adds a Forks Count column using the addAgGridColumnDefinition function
We then use the updateCurrentLayout function in Layout API to update the Layout to include the newly created column (see Updating Layouts for more details)

Expand to see how the Column Definition is added

Try It Out

Click the button to add a Forks Count column (and note how it is added to the Layout)

Removing ColDefs

The removeAgGridColumnDefinition function enables safe run-time deletion of existing AG Grid ColDefs.

removeAgGridColumnDefinition

columnId: string

void

Removes existing AG Grid Columns

Deleting Column Definitions at Runtime

Fork Fork

In this example we provide a button that deletes the License column using the removeAgGridColumnDefinition function.

Expand to see how the Column Definition is deleted

Try It Out

Click the button to remove the License column

Setting ColDefs

The setAgGridColumnDefinitions function enables setting multiple AG Grid Column Definitions at run-time in a single step.

setAgGridColumnDefinitions

columnDefinitions: (ColDef | ColGroupDef)[]

void

Set multiple AG Grid Columns

Setting Column Definitions at Runtime

Fork Fork

In this example the grid starts with many columns visible
Clicking the button replaces all Column Definitions in a single step using the setAgGridColumnDefinitions function
The new set contains just 4 columns: Framework, Language, GitHub Stars and License
The current Layout is also updated so it stays in sync with the new columns (see Updating Layouts for more details)

Expand to see how the Column Definitions are set

const compactColumnDefs = [
  {
    colId: 'name',
    field: 'name',
    headerName: 'Framework',
    cellDataType: 'text',
    width: 200,
  },
  {
    colId: 'language',
    field: 'language',
    cellDataType: 'text',
    width: 150,
  },
  {
    colId: 'github_stars',
    field: 'github_stars',
    headerName: 'GitHub Stars',
    cellDataType: 'number',
    width: 150,
  },
  {
    colId: 'license',
    field: 'license',
    cellDataType: 'text',
    width: 180,
  },
];

context.adaptableApi.gridApi.setAgGridColumnDefinitions(compactColumnDefs);

context.adaptableApi.layoutApi.updateCurrentLayout(layout => {
  layout.TableColumns = ['name', 'language', 'github_stars', 'license'];
  return layout;
});

Try It Out

Click the button to replace the Column Definitions with the compact set (and note how the Layout is updated)

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

const compactColumnDefs = [
  {
    colId: 'name',
    field: 'name',
    headerName: 'Framework',
    cellDataType: 'text',
    width: 200,
  },
  {
    colId: 'language',
    field: 'language',
    cellDataType: 'text',
    width: 150,
  },
  {
    colId: 'github_stars',
    field: 'github_stars',
    headerName: 'GitHub Stars',
    cellDataType: 'number',
    width: 150,
  },
  {
    colId: 'license',
    field: 'license',
    cellDataType: 'text',
    width: 180,
  },
];

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Setting Column Defs',
  dashboardOptions: {
    customToolbars: [
      {
        name: 'Custom Buttons',
        toolbarButtons: [
          {
            label: 'Set Compact Column Definitions',
            buttonStyle: {
              tone: 'info',
              variant: 'outlined',
            },
            onClick: (
              _button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.gridApi.setAgGridColumnDefinitions(
                compactColumnDefs
              );

              context.adaptableApi.layoutApi.updateCurrentLayout(layout => {
                layout.TableColumns = [
                  'name',
                  'language',
                  'github_stars',
                  'license',
                ];
                return layout;
              });
            },
          },
        ],
      },
    ],
  },
  initialState: {
    Dashboard: {
      PinnedToolbars: ['Custom Buttons'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'week_issue_change',
            'license',
            'language',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'github_stars',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

PreviousSetting AG Grid Cell Data Types NextConfiguring ColDefs at Design Time