AdapTable Version:

Framework:

Interacting with AG Grid Column Defs

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
AdapTable treats each ColDef property on a case by case basis
This page anaylses the different use cases and the general principles involved

AG Grid allows users to define the columns in the Grid using the colDefs property in Grid Options.

This step is mandatory for AdapTable users, also, who will then reference the ColDef Id in their Layouts.

However not all properties in ColDefs are treated equally by AdapTable - some are ignored, some are required and others are used only if the preferred alternative in AdapTable is not provided.

The full details of how AdapTable treats each ColDef property are listed below.

AG Grid also allows users to manage ColDefs (despite being immutable) at run-time.

AdapTable supports this and provides a set of useful functions to ensure everything hangs together.

Managing ColDefs at Run-Time

AG Grid's Column Definitions are immutable.

It is possible, at runtime, to add, update or delete ColDefs, but only by using 2 sets of AG Grid API functions:

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 how columns can be updated at run-time.

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

These functions ensure that AG Grid columns are added, updated or deleted correctly, while 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

As noted above, when updating columns AG Grid differentiates between 'stateful' and other properties.

AdapTable follows this same distinction in how it facilitates updating AG Grid's columns at run-time.

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

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,
        },
      ],
    },
  },
};

Other Column 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 ColDefs

AdapTable's GridApi contains an addAgGridColumnDefinition function to enable new AG Grid Column Definitions to be safely 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

AdapTable's GridApi additionally contains a removeAgGridColumnDefinition function to enable existing AG Grid Column Definitions to be safely deleted at run-time.

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

Configuring ColDefs

AG Grid and AdapTable each have a mechanism for developers to provide information about Grid Columns:

AG Grid ColDef Properties - define column behaviour across the Grid
AdapTable Layouts - define Column behaviour and properties for named sets of Columns

The fundamental difference between the 2 properties is Scope Usage.

Important

ColDefs set full and exclusive Column behaviour for the lifetime of the Application
Layouts support multiple, mutually exclusive use cases - Columns can behave differently in different Layouts

Because AdapTable supports multiple Layouts, it cannot simply just read the properties defined in ColDefs.

Note

This is because 2 different Layouts might want to treat the same Column property differently
For instance it is very common to set different visibility, column order, or row grouping in different Layouts

As a result, AdapTable needs to decide on initial Layout behaviour on a per-ColDef property basis.

Essentially, AdapTable responds to AG Grid ColDef properties in 3 different ways.

Depending on the use case, it will do one of the following for each property:

ignore - the property is never invoked or used
respect - if provided, AdapTable will use it in its own functionality

Caution

AdapTable generally ignores ColDef props that sets same values as available in Layouts, e.g. group, pivot, pin
But respects (usually in Layout Editor) ColDef props that set behaviour e.g. enableGroup, enableValue, resizable

fall back on - property still works if AdapTable's preferred implementation is not provided

Note

The majorify of AG Grid's ColDef properties do not appear in any of these 3 lists
This is because AdapTable has no direct relationship with them, and they perform their intended AG Grid purpose

Ignored

There are some ColDef properties which AdapTable simply ignores - they are never read nor acted upon.

The intended behaviour needs, instead, to be provided via AdapTable's Layout properties.

Pivoting

ColDef	AG Grid Purpose	AdapTable Layout Behaviour
`pivot`	Pivots a Column	Only columns in `PivotColumns` are pivoted
`initialPivot`	Pivots new Column	Only columns in `PivotColumns` are pivoted
`pivotIndex`	Pivot Column index	Columns are pivoted by `PivotColumns` order
`initialPivotIndex`	New Pivot Column index	Columns are pivoted by `PivotColumns` order

Row Grouping

ColDef	AG Grid Purpose	AdapTable Layout Behaviour
`rowGroup`	Groups a Column	Only columns in `RowGroupColumns` are grouped
`initialRowGroup`	Groups new Column	Only columns in `RowGroupColumns` are grouped
`rowGroupIndex`	Grouped Column index	Columns grouped by `RowGroupColumns` order
`initialRowGroupIndex`	New Grouped Column index	Columns grouped by `RowGroupColumns` order

Aggregating

ColDef	AG Grid Purpose	AdapTable Layout Behaviour
`aggFunc`	Agg Func	Only Aggregations in `TableAggregationColumns` are evaluated
`initialAggFunc`	New Agg Func	Only Aggregations in `TableAggregationColumns` are evaluated

Pinning

ColDef	AG Grid Purpose	AdapTable Layout Behaviour
`pinned`	Pins a Column	Only columns in `ColumnPinning` are pinned
`initialPinned`	Pins new Column	Only columns in `ColumnPinning` are pinned
`lockPinned`	Prevents Pinning a Column	Column can still be pinned in Layout and UI

Sorting

ColDef	AG Grid Purpose	AdapTable Layout Behaviour
`sort`	Sorts a Column	Only columns in `ColumnSorts` are sorted
`initialSort`	Sorts new Column	Only columns in `ColumnSorts` are sorted
`sortIndex`	Sorted Column index	Columns sorted by the order in `ColumnSorts`
`initialSortIndex`	New Sorted Column index	Columns sorted by the order in `ColumnSorts`
`sortingOrder`	Order of Sort Directions	Sort Directions provided in `ColumnSorts`

Visibility

ColDef	AG Grid Purpose	AdapTable Layout Behaviour
`hide`	Hides a Column	Any column in `TableColumns` is visible (unless overridden in `ColumnVisibility`)
`initialHide`	Hides a new Column	Any column in `TableColumns` is visible (unless overridden in `ColumnVisibility`)

Sizing

ColDef	AG Grid Purpose	AdapTable Layout Behaviour
`initialWidth`	Width for new Columns	Only sizing in `ColumnSizing` is used
`initialFlex`	Flex for new Columns	Only sizing in `ColumnSizing` is used

Note

Unlike with most other ColDef properties that have values, flex and width are not ignored by AdapTable
Instead they are used if the Column's property is not explicitly overridden in the Layout's ColumnSizing

Leveraged

There are many ColDef properties which, if provided, are respected - and used - by AdapTable:

ColDef	AG Grid Purpose	AdapTable Behaviour
`field`	Finds item in Grid Data Source	Becomes Adaptable Column `field` property
`colId`	Unique Id for Column	Becomes Adaptable Column `columnId` property
`type`	Used for Column Templating	Used for Column Types Scope
`cellDataType`	Column's data type	Used to infer Adaptable Column's Data Type
`enablePivot`	Column is Pivotable in UI	Respected by Pivot Layout UI Wizard
`enableRowGroup`	Column is Groupable in UI	Respected by Table Layout UI Wizard
`enableValue`	Column is Aggregatable in UI	Respected by Pivot Layout UI Wizard
`defaultAggFunc`	Default Agg Func	Respected by Table Layout UI Wizard
`allowedAggFuncs`	Allowed Agg Funcs	Respected by Table Layout UI Wizard
`sortable`	Column is Sortable in UI	Respected by Table Layout UI Wizard
`resizable`	Column is Resizable in UI	Respected by Table Layout UI Wizard
`suppressMovable`	Column is not Movable in UI	Respected by Table Layout UI Wizard

Note

The resizable property is only used if it is not explicitly overridden by Resizable in the Layout's ColumnSizing object

AdapTable Preference

There are a few AG Grid ColDef properties for which AdapTable provides an alternative implementation.

These properties will be evaluated, but only if the AdapTable equivalent has not been provided.

Note

We strongly recommend using the AdapTable equivalent in all these use cases where possible
Any objects created are saved to AdapTable State and there is tight integration with other AdapTable features

ColDef	AG Grid Purpose	Preferred AdapTable Equivalent
`valueFormatter`	Formats a Cell	Display Formats
`comparator`	Provides custom sort	Custom Sort
`editable`	Sets Column Editability	AdapTable Cell Editability

In addition, the Layout's ColumnSizing object contains 5 properties which override ColDef props.

However if one of these is not provided, then the ColDef equivalent is used instead:

AdapTable `ColumnSizing` Property Used if Provided	ColDef Fallback property
`Flex`	`flex`
`Width`	`width`
`MinWidth`	`minWidth`
`MaxWidth`	`maxWidth`

PreviousSetting AG Grid Cell Data Types NextCreating Array Columns

Framework: