# Adaptable Column

Canonical page: https://www.adaptabletools.com/docs/dev-guide-columns-adaptable-column

- 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](https://www.adaptabletools.com/docs/handbook-action-column/index.md), [Calculated](https://www.adaptabletools.com/docs/handbook-calculated-column/index.md) and [FreeText](https://www.adaptabletools.com/docs/handbook-freetext-column/index.md) Columns
  - Columns dynamically created by AG Grid (e.g. Row Grouped Columns, Pivot Columns, Tree Columns etc.)
- Many objects in [Initial Adaptable State](https://www.adaptabletools.com/docs/technical-reference-initial-state/index.md) rely heavily on Columns and generally use the `columnId` property

When AdapTable is being initialised it dynamically creates a collection of [`AdaptableColumn`](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md) objects.

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

- Based on the `ColDef` provided in the `columnDefs` property of [GridOptions](https://www.ag-grid.com/javascript-data-grid/grid-interface/#grid-options)

- Created for each Special Column provided to AdapTable (of which there are 3 types):
  - [Action Columns](https://www.adaptabletools.com/docs/handbook-action-column/index.md)
  - [Calculated Column](https://www.adaptabletools.com/docs/handbook-calculated-column/index.md)
  - [FreeText Columns](https://www.adaptabletools.com/docs/handbook-freetext-column/index.md)

- Matching columns that are dynamically created by AG Grid - these include:
  - [Row Grouped Columns](https://www.adaptabletools.com/docs/handbook-grouping-rows/index.md)
  - [Pivot Result Columns](https://www.adaptabletools.com/docs/handbook-layouts-pivot/index.md)
  - [Tree Grid Key Columns](https://www.adaptabletools.com/docs/handbook-tree-data-grid/index.md)
  - [Selection Column](https://www.adaptabletools.com/docs/handbook-layouts-table-row-selection/index.md)

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

## AdapTable Column Properties

Adaptable Columns are defined using the [`AdaptableColumn`](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md) object which contains a large number of properties.

These properties are evaluated by AdapTable when the Application starts.

### AdaptableColumn Object: Full Properties

The [`AdaptableColumn`](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md) object is derived from [`AdaptableColumnBase`](https://www.adaptabletools.com/docs/reference/adaptablecolumnbase.md) which contains these properties:

| Property | Type | Description |
| --- | --- | --- |
| [columnId](https://www.adaptabletools.com/docs/reference/adaptablecolumnbase.md#columnid) | `string` | Name of Column in AG Grid (e.g. field or colId) |
| [columnTypes](https://www.adaptabletools.com/docs/reference/adaptablecolumnbase.md#columntypes) | `string[]` | Column Types of the Column |
| [dataType](https://www.adaptabletools.com/docs/reference/adaptablecolumnbase.md#datatype) | [`AdaptableColumnDataType`](https://www.adaptabletools.com/docs/reference/adaptablecolumndatatype.md) | DataType of the Column |
| [friendlyName](https://www.adaptabletools.com/docs/reference/adaptablecolumnbase.md#friendlyname) | `string` | How Column is referred to in Adaptable UI; `Caption` property in AG Grid |
| [IsReadOnly](https://www.adaptabletools.com/docs/reference/adaptablecolumnbase.md#isreadonly) | `boolean` | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of &#39;Full&#39;) |

The full list of properties in the [`AdaptableColumn`](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md) object is:

| Property | Type | Description |
| --- | --- | --- |
| [aggregatable](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#aggregatable) | `boolean` | Is Column able to display aggregations (e.g. &#39;sum&#39;) when grouped |
| [aggregationFunction](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#aggregationfunction) | `string` | Custom Aggregation function for the Column |
| [availableAggregationFunctions](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#availableaggregationfunctions) | `string[]` | Available Aggregations for the Column |
| [columnGroup](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#columngroup) | [`AdaptableColumnGroup`](https://www.adaptabletools.com/docs/reference/adaptablecolumngroup.md) | The parent Column group (if Column belongs to one) |
| [exportable](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#exportable) | `boolean` | Whether the Column can be included in Reports |
| [field](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#field) | `Extract<keyof TData, string>` | Field in the row to get cell data from |
| [fieldOnly](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#fieldonly) | `boolean` | Is the Column ONLY available as a field and never visible |
| [filterable](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#filterable) | `boolean` | Is Column able to be filtered |
| [flex](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#flex) | `number` | Flex details of the Column |
| [groupable](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#groupable) | `boolean` | Can Column form a Row Group |
| [hideable](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#hideable) | `boolean` | Can Column be removed from the grid |
| [isActionColumn](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#isactioncolumn) | `boolean` | Is Column an Action Column |
| [isCalculatedColumn](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#iscalculatedcolumn) | `boolean` | Is Column a Calculated Column |
| [isFixed](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#isfixed) | `boolean` | Is Column pinned or locked into position |
| [isFreeTextColumn](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#isfreetextcolumn) | `boolean` | Is Column a Free Text Column |
| [isGeneratedPivotResultColumn](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#isgeneratedpivotresultcolumn) | `boolean` | Is Column a generated Pivot Result Column |
| [isGeneratedRowGroupColumn](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#isgeneratedrowgroupcolumn) | `boolean` | Is Column a generated Row Group Column |
| [isGeneratedSelectionColumn](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#isgeneratedselectioncolumn) | `boolean` | Is Column a generated Selection Column |
| [isGrouped](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#isgrouped) | `boolean` | Is Column currently Row-Grouped |
| [isPivotTotalColumn](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#ispivottotalcolumn) | `boolean` | Is Column a Pivot Total Column (GrandTotal, GroupTotal, AggregationTotal) |
| [isPrimaryKey](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#isprimarykey) | `boolean` | Is this the Primary Key Column |
| [isSparkline](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#issparkline) | `boolean` | Is it a Sparkline Column |
| [isTreeColumn](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#istreecolumn) | `boolean` | Whether Column is the Tree Column (in Tree View) |
| [isUIHiddenColumn](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#isuihiddencolumn) | `boolean` | Whether Column is always hidden in UI but still available programmatically |
| [moveable](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#moveable) | `boolean` | Can Column be moved at run-time to a new position |
| [pinned](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#pinned) | `'left' \| 'right' \| false` | The pinned position of the Column |
| [pivotable](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#pivotable) | `boolean` | Can Column be used in a Pivot Layout |
| [queryable](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#queryable) | `boolean` | Can the Column be in included in Queries / Expressions |
| [readOnly](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#readonly) | `boolean` | Is Column editable; returns FALSE if Column has conditional/dynamic editability, assuming some rows are editable |
| [resizable](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#resizable) | `boolean` | Is Column resizable |
| [sortable](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#sortable) | `boolean` | Is Column sortable |
| [userAllowedAggFuncs](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#userallowedaggfuncs) | `string[]` | `allowedAggFuncs` from the column `colDef` or `defaultColDef` as supplied in Grid Options<br/>(before Adaptable rewrites `allowedAggFuncs` for the standard Value Aggregation menu). |
| [visible](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#visible) | `boolean` | Is Column currently visible |
| [width](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#width) | `number` | Column width |
| [IsReadOnly](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md#isreadonly) | `boolean` | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of &#39;Full&#39;) |

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](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-initial-state/index.md).

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`.

If you are holding an AG Grid `ColDef` and need the matching AdapTable Column, use [`getColumnForColDef`](https://www.adaptabletools.com/docs/reference/columnapi.md#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](https://www.adaptabletools.com/docs/ui-expression-editor/index.md) and all panels in the [Settings Panel](https://www.adaptabletools.com/docs/ui-settings-panel/index.md).

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](https://www.adaptabletools.com/docs/technical-reference-column/index.md).

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](https://www.adaptabletools.com/docs/handbook-column-filter/index.md) are available.

AdapTable derives the value of the DataType, in the first instance by using the [Cell Data Type](https://www.adaptabletools.com/docs/dev-guide-aggrid-cell-data-types/index.md) of the AG Grid Column Definition if provided.

- The [Cell Data Type](https://www.adaptabletools.com/docs/dev-guide-aggrid-cell-data-types/index.md) 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](https://www.adaptabletools.com/docs/dev-guide-columns-column-types/index.md)).

### How are the 'Identity' Properties set?

This table illustrates how the value for each property is worked out by AdapTable:

| Property       | AG Grid Column Property                                                                                                                       | Action Column                                                               | Calculated Column                                                                                           | FreeText Column                                                                                         |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|                | `ColumnDefs` in [GridOptions](https://www.ag-grid.com/javascript-data-grid/grid-interface/#grid-options)                                      | [Action Column Options](https://www.adaptabletools.com/docs/technical-reference-action-column/index.md) | [Calculated Column InitialState](https://www.adaptabletools.com/docs/technical-reference-calculated-column/index.md) | [FreeText Column InitialState](https://www.adaptabletools.com/docs/technical-reference-freetext-column/index.md) |
| `columnId`     | `colId` if set, otherwise `field`                                                                                                             | `columnId`                                                                  | `ColumnId`                                                                                                  | `ColumnId`                                                                                              |
| `friendlyName` | AG Grid ColumnAPI function: `getDisplayNameForColumn`                                                                                         | `friendlyName`                                                              | `FriendlyName`                                                                                              | `FriendlyName`                                                                                          |
| `dataType`     | From [AG Grid cellDataType](https://www.adaptabletools.com/docs/dev-guide-aggrid-cell-data-types/index.md) if provided; otherwise guesses from first Row's data | n/a                                                                         | `DataType`                                                                                                  | `DataType`                                                                                              |
| `columnTypes`  | From [AG Grid type](https://www.adaptabletools.com/docs/dev-guide-columns-column-types/index.md)                                                                | `actionColumn`                                                              | `calculatedColumn`                                                                                          | `freeTextColumn`                                                                                        |

See [Column Types: Scope](https://www.adaptabletools.com/docs/dev-guide-columns-column-types/index.md) 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`.

- Many of these are derived from functions you supply in [Adaptable Options](https://www.adaptabletools.com/docs/technical-reference-adaptable-options/index.md)
- 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`

- 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

- Do **not cache** these values
- Re-fetch the Column via [Column API](https://www.adaptabletools.com/docs/dev-guide-columns-adaptable-column/index.md#column-api) (e.g. [`getColumnWithColumnId`](https://www.adaptabletools.com/docs/reference/columnapi.md#getcolumnwithcolumnid)) whenever you need the current state

## Types of AdapTable Columns

It is worth dividing up AdapTable Columns into 3 groups.

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

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 the `isColumnExportable` property in [Export Options](https://www.adaptabletools.com/docs/technical-reference-exporting/index.md)
  - `queryable` - derived from `isColumnQueryable` property [Expression Options](https://www.adaptabletools.com/docs/technical-reference-expression/index.md)

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

- [Calculated Columns](https://www.adaptabletools.com/docs/handbook-calculated-column/index.md)
- [FreeText Columns](https://www.adaptabletools.com/docs/handbook-freetext-column/index.md)
- [Action Columns](https://www.adaptabletools.com/docs/handbook-action-column/index.md)

In these cases AdapTable uses a combination of:
- properties provided in the object definitions in [Initial Adaptable State](https://www.adaptabletools.com/docs/technical-reference-initial-state/index.md) (or [Action Column Options](https://www.adaptabletools.com/docs/technical-reference-action-column/index.md) for Action Columns)
- sensible defaults for the Column (e.g. Action Columns have `readOnly` set 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:

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

- [Row Grouped Columns](https://www.adaptabletools.com/docs/handbook-grouping-rows/index.md)
- [Pivot Result Columns](https://www.adaptabletools.com/docs/handbook-layouts-pivot/index.md)
- [Tree Grid Key Columns](https://www.adaptabletools.com/docs/handbook-tree-data-grid/index.md)
- [Selection Column](https://www.adaptabletools.com/docs/handbook-layouts-table-row-selection/index.md)

## 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](https://www.adaptabletools.com/docs/ui-column-menu/index.md)).

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

Most commonly you retrieve a Column through the [Column API](https://www.adaptabletools.com/docs/dev-guide-columns-adaptable-column/index.md#column-api) using its `columnId` and then read its properties:

```ts
// 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:

```ts
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:

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

Column Options and the Column API are in the [Column Technical Reference](https://www.adaptabletools.com/docs/technical-reference-column/index.md)
