Adaptable Column

View as Markdown

Summary

  • AdapTable creates an AdaptableColumn object for every AG Grid Column each time the Application starts
  • AdapTable Columns are created from 3 sources:
    • Every column defined in columnDefs property of AG Grid GridOptions
    • Special Columns used in AdapTable - i.e. Action, Calculated and FreeText Columns
    • Columns dynamically created by AG Grid (e.g. Row Grouped Columns, Pivot Columns, Tree Columns etc.)
  • Many objects in Initial Adaptable State rely heavily on Columns and generally use the columnId property

When AdapTable is being initialised it dynamically creates a collection of AdaptableColumn objects.

There is one Adaptable Column for every column in the Grid, and they can be of 3 types:

Hint

See below for details on how AdapTable sets the properties of the AdapTable Column

AdapTable Column Properties

Adaptable Columns are defined using the AdaptableColumn object which contains a large number of properties.

These properties are evaluated by AdapTable when the Application starts.

Deep Dive

AdaptableColumn Object: Full Properties

However, these properties fall into 4 broad groups which makes them easier to reason about.

Identity Props

The "Identity Props" define who the Column is.

They are probably the most important, and frequently used, properties and include:

columnId

The columnId property is the primary way of referring to the Column, and what is generally used in Initial Adaptable State.

It is the stable key for the Column throughout AdapTable.

AdapTable sets columnId to the AG Grid colId if one is provided, otherwise to the Column's field.

Hint

If you are holding an AG Grid ColDef and need the matching AdapTable Column, use getColumnForColDef rather than trying to work out the columnId yourself.

friendlyName

The friendlyName property sets how the Column is referred to throughout the AdapTable UI.

This includes the Expression Editor and all panels in the Settings Panel.

It is usually derived automatically from the headerName property in the AG Grid Column definition, but it can be provided explicitly in the columnFriendlyName function property in Column Options.

Hint

This is useful where you might have multiple columns with the same header (e.g. 'Price' or 'Bid') and you want to be able to differentiate between them in the UI

dataType

The important dataType property determines whether the Column is a number, string, date, boolean etc.

This influences many things in AdapTable e.g. what Column Filters are available.

AdapTable derives the value of the DataType, in the first instance by using the Cell Data Type of the AG Grid Column Definition if provided.

Note

  • The Cell Data Type is assigned to the Column's AG Grid ColDef definition using the cellDataType property
  • It is strongly advised that all AG Grid Col Definitions should include this property

columnTypes

The columnTypes property is based off the type property of the AG Grid Column Definition.

AdapTable will add additional values to this prop in some use cases (as detailed in this tutorial).

Deep Dive

How are the 'Identity' Properties set?

Find Out More

See Column Types: Scope for how to provide column types that are available when scoping objects

Capability flags

These properties define what a User is allowed to do with the Column: sortable, filterable, groupable, pivotable, aggregatable, queryable, exportable, moveable, hideable, readOnly.

Note

  • Many of these are derived from functions you supply in Adaptable Options
  • e.g. exportable from isColumnExportable, queryable from isColumnQueryable

Column-kind flags

These properties define what sort of Column it is: isCalculatedColumn, isFreeTextColumn, isActionColumn, isPivotTotalColumn, isGeneratedRowGroupColumn, isGeneratedSelectionColumn, isGeneratedPivotResultColumn, isSparkline

Live grid-state

These properties define the Column's current state in the Grid: visible, pinned, width, flex, isGrouped, isFixed

Caution

  • The Live grid-state properties reflect the state of the Column at the moment the object was retrieved
  • If the Column is subsequently moved, pinned, or grouped etc, a previously retrieved AdaptableColumn will be stale

Hint

Types of AdapTable Columns

It is worth dividing up AdapTable Columns into 3 groups.

Note

The type of the AdapTable Column also influences how AdapTable evaluates the associated properties

Regular Columns

Regular columns are those which are defined initially in AG Grid GridOptions object.

AdapTable will work out the values for that Column's properties in AdapTable Column in 2 ways:

  • using the values provided in the AG Grid Column Definition

Note

Examples are field, groupable, movable, sortable - all based off similar properties in Grid Options

  • reading some properties provided in Adaptable Options, for example:

Special Columns

AdapTable can create 3 'Special Columns' which are not defined in Grid Options but through AdapTable itself:

In these cases AdapTable uses a combination of:

Derived Columns

There are various use cases where AG Grid will create a Column that is not provided by the developer in ColumnDefs. These include:

Note

When this happens AdapTable will always create a matching Column, also provided dynamically

Column API

Using AdapTable Columns

Run-time users leverage AdapTable Columns continuously but indirectly through AG Grid.

The overwhelming majority of users of AdapTable will not need to be aware of the existence of AdapTable Columns.

Developers will frequently access AdapTable Columns since they are often contained in Context objects supplied to functions, and used elsewhere in AdapTable (e.g. in the Column Menu).

Important

Developers will never create AdapTable Columns as they are provided dynamically by AdapTable

Most commonly you retrieve a Column through the Column API using its columnId and then read its properties:

// get a single Column and inspect it
const priceColumn = adaptableApi.columnApi.getColumnWithColumnId('price');

if (priceColumn) {
  console.log(priceColumn.friendlyName); // e.g. 'Bid Price'
  console.log(priceColumn.dataType); // e.g. 'number'
  console.log(priceColumn.queryable); // capability flag
}

You can use the column-kind flags to work out what sort of Column you are dealing with:

const column = adaptableApi.columnApi.getColumnWithColumnId('rating');

if (column?.isCalculatedColumn) {
  // handle Calculated Columns differently to regular Columns
}

If you are working with AG Grid directly and have a ColDef (for example inside an AG Grid callback), you can get straight to the matching AdapTable Column:

// map an AG Grid ColDef to its AdapTable Column
const abColumn = adaptableApi.columnApi.getColumnForColDef(colDef);

Find Out More

Column Options and the Column API are in the Column Technical Reference