Adaptable Column
Summary
- AdapTable creates an
AdaptableColumnobject for every AG Grid Column each time the Application starts - AdapTable Columns are created from 3 sources:
- Every column defined in
columnDefsproperty 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.)
- Every column defined in
- Many objects in Initial Adaptable State rely heavily on Columns and generally use the
columnIdproperty
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:
-
Based on the
ColDefprovided in thecolumnDefsproperty of GridOptions -
Created for each Special Column provided to AdapTable (of which there are 3 types):
-
Matching columns that are dynamically created by AG Grid - these include:
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
ColDefdefinition using thecellDataTypeproperty - 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.
exportablefromisColumnExportable,queryablefromisColumnQueryable
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
AdaptableColumnwill be stale
Hint
- Do not cache these values
- Re-fetch the Column via Column API (e.g.
getColumnWithColumnId) whenever you need the current state
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:
exportable- derived from theisColumnExportableproperty in Export Optionsqueryable- derived fromisColumnQueryableproperty Expression Options
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:
- properties provided in the object definitions in Initial Adaptable State (or Action Column Options for Action Columns)
- sensible defaults for the Column (e.g. Action Columns have
readOnlyset to true)
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