Configuring Free Text Columns

View as Markdown

Summary

  • Free Text Columns can be defined at design-time using Free Text Column Initial State
  • The Free Text Column API can be used to add values programmatically at run-time

Free Text Columns are defined in initialState.FreeTextColumn.FreeTextColumns — see Free Text Column Initial Adaptable State and FreeTextColumn.

Part of FreeTextColumnPurpose
ColumnIdId used in Layouts, filters, and API
FriendlyNameHeader text in the UI (optional)
FreeTextColumnSettingsRequired DataType; layout flags (Filterable, Sortable, …); optional CellDataType
DefaultValueShown in every cell until the user overrides
FreeTextStoredValuesPer-row values keyed by PrimaryKey

Run-time updates use FreeTextColumnApi.setStoredValues (below).

Defining Free Text Columns

Developer Guide

Defining a Free Text Column

There are (up to) 6 properties that you need to provide:

const initialState: InitialState = {
  FreeTextColumn: {
    FreeTextColumns: [
      {
        ColumnId: 'comments',
        FriendlyName: 'Ops Note',
        FreeTextStoredValues: [
          { PrimaryKey: 24195339, FreeText: 'Used by US team' },
          { PrimaryKey: 82095231, FreeText: 'Required by Support' },
        ],
        FreeTextColumnSettings: {
          Resizable: true,
          DataType: 'text',
        },
      },
      {
        ColumnId: 'orderCode',
        FriendlyName: 'Order Code',
        DefaultValue: 123,
        FreeTextColumnSettings: {
          DataType: 'number',
          Sortable: false,
          SuppressMenu: true,
        },
      },
      {
        ColumnId: 'isUsed',
        FriendlyName: 'Is Used',
        DefaultValue: false,
        FreeTextColumnSettings: {
          DataType: 'boolean',
          Filterable: true,
        },
      },
    ],
  },
};
1
Id for the Free Text Column

This value is used to refer to the Column in State

2
Column Name (if the Id property is not suitable)

This value is used to refer to the Column in AdapTable UI

3
DataType for the Column

Whether the Column is Text Number Date or Boolean

Is only mandatory property in FreeTextColumnSettings

AdapTable provides an appropriate Cell Editor based on the DataType provided here

4
Default Value (Optional)

Used in each cell unless explicitly overridden by the User

5
Initial Stored Values (Optional)

Initial values to show in the column.

Each is keyed against the Primary Key value for the Row.

6
Other Column Settings (Optional)

Provide additional settings for the Column (e.g. filterable, pivotable, resizable, sortable etc.)

Hint

Adding Values Programmatically

A commonly used function in Free Text Column API is setStoredValues which allows you to update values stored in Free Text Columns programmatically.

setStoredValues

columnId: string, values: FreeTextStoredValue[], action: 'All' | 'Conflicting' | 'None'
void
Adds Stored Values to a FreeText Column
Adding FreeText Values via API
Fork
  • The demo starts with 3 stored values in the OpsNote Free Text column (adaptableOptions.ts)
  • Each toolbar button applies the same payload : update Angular (PK 24195339), and add React (PK 10270250) - with a different replaceAction:
    • None — only adds the new Stored Value; existing ones are left unchanged
    • Conflicting — updates the overlapping Stored Value and adds the new one; other Stored Values remain
    • All — replaces every Stored Value with just the payload
  • Use Reset to restore the initial 3 Stored Values (replaceAction: 'All')
Try It Out

Click None, then Reset, and compare with Conflicting and All

Loading demo…

AG Grid Column Definitions

Typically Free Text Columns are provided only in Initial Adaptable State and not also defined in Grid Options.

However sometimes it is required to define the Free Text Column in AG Grid - e.g. if you want to show an AG Grid tooltip on the cell value.

This is possible by specifying a Column Type of freeTextColumn in the AG Grid Column Definition.

Hint

Make sure ColId in the Column Definition and ColumnId in the Custom Column definition are the same value

Find Out More

See Adding Special Column Types for more details and an accompanying demo

AG Grid Cell Data Type

AG Grid provides a Cell Data Type (cellDataType) property which can be attached to one, or more, columns.

AdapTable allows users to leverage, and assign, an application-registered AG Grid Cell Data Type when creating a Free Text Column.

Caution

  • The baseDataType (or extendsDataType) must be compatible with the Free Text Column's AdapTable DataType
  • If this is not provided then AdapTable will use the Free Text Column's DataType property

This is done via the optional CellDataType property in FreeTextColumnSettings:

Hint

  • The key benefit is the Free Text Column automatically inherits everything the registered Cell Data Type provides
  • e.g. its valueFormatter, valueParser and cell editor
{
  ColumnId: 'TargetPrice',
  FriendlyName: 'Target Price',
  FreeTextColumnSettings: {
    DataType: 'number', // AdapTable uses `number` for AQL, filtering and menus...
    CellDataType: 'pricing', // ...but AG Grid renders the cell using the registered `pricing` type
  },
},
Free Text Columns: AG Grid Cell Data Type
Fork
  • This demo registers 2 custom AG Grid Cell Data Types in dataTypeDefinitions (in AG Grid GridOptions), each with its own valueFormatter:
    • currency - formats a number as a USD currency value
    • percentage - formats a number (0-1) as a percentage
  • It then defines 2 Free Text Columns which have an AdapTable DataType of number but a different CellDataType:
    • Target Price - an editable currency value (with 3 initial Stored Values)
    • Completion - an editable percentage value (defaulting to 50%)
  • Because the AdapTable DataType is still number, both columns filter, sort and edit as numbers
Try It Out
  • Edit a cell in the Target Price Column - you enter a plain number but it displays as currency
  • Look at gridOptions.ts to see how the currency and percentage Cell Data Types are registered
Loading demo…