Configuring Free Text Columns

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

Defining Free Text Columns

Free Text Columns can be defined in Free Text Column Initial Adaptable State.

Each FreeTextColumn object contains 2 useful properties that can be provided if required:

FreeTextStoredValues - allows the Free Text Column to be 'pre-populated' with relevant data
DefaultValue - enables each cell to display a default value unless explicitly overridden by the User

Developer Guide

Defining a Free Text Column

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

// Provide 3 Free Text Columns
// 1. OpsNote - string column with 3 initial values
// 2. OrderCode - numeric column with default of 123
// 3. LastSpoken - a date Column
const initialState: InitialState = {
  FreeTextColumn: {
    FreeTextColumns: [
      {
        ColumnId: 'OpsNote',
        FriendlyName: 'Ops Note',
        FreeTextStoredValues: [
          { PrimaryKey: 12, FreeText: 'Dispatch asap' },
          { PrimaryKey: 15, FreeText: 'Angry client' },
          { PrimaryKey: 21, FreeText: 'Big order' },
        ], 
        FreeTextColumnSettings: {
          DataType: 'text',
          Aggregatable: false,
        },
      },
      {
        ColumnId: 'OrderCode',
        FriendlyName: 'Order Code',
        DefaultValue: 123, 
        FreeTextColumnSettings: {
          DataType: 'number',
          Sortable: false,
          SuppressMenu: true,
        },
      },
      {
        ColumnId: 'LastSpoken',
        FriendlyName: 'Last Spoken',
        FreeTextColumnSettings: {
          DataType: 'date',
          Filterable: true,
        },
      },
    ],
  },
}

Id for the Free Text Column

This value is used to refer to the Column in State

Column Name (if the Id property is not suitable)

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

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

Default Value (Optional)

Used in each cell unless explicitly overridden by the User

Initial Stored Values (Optional)

Initial values to show in the column.

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

Other Column Settings (Optional

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

Hint

To prevent filtering on Free Text Columns, set enableFilterOnSpecialColumns to false in Column Filter Options
This will also disallow filtering on all Calculated Columns and Action Columns

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

This is a useful function that allows you to add values to a FreeText Column programmatcally.

The definition is:

  setStoredValues(
    columnId: string,
    storedValues: FreeTextStoredValue[],
    replaceAction: 'All' | 'Conflicting' | 'None'
  ): void;

The replaceAction parameter defines the rules for how the new Stored Values should interact with any existing (and potentially clashing) cell values in the Column.

The property can be one of 3 values with the following behaviour for each:

All - replaces all existing Stored Values for the Column with the new ones even if provided cells are currently empty
Conflicting - adds all given stored values and replaces any existing ones which clash with the new set
None - skips primary keys that already have a Stored Value; only adds entries for keys that are not yet present

// Replace all Existing Free Text Values in the Column with the 2 provided:
const values: FreeTextStoredValue[] = [
    { PrimaryKey: 5, FreeText: 'Fifth' },
    { PrimaryKey: 6, FreeText: 'Sixth' }
  ];
  api.freeTextColumnApi.setStoredValues('OpsNote', values, 'All');

Adding FreeText Values via API

Fork Fork

The demo starts with 3 Stored Values in the Ops Note FreeText Column
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

import {
  AdaptableButton,
  AdaptableOptions,
  CustomToolbarButtonContext,
  FreeTextStoredValue,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

const COLUMN_ID = 'OpsNote';

const initialStoredValues: FreeTextStoredValue[] = [
  {PrimaryKey: 24195339, FreeText: 'Used by the US team'},
  {PrimaryKey: 224663696, FreeText: 'My personal favourite'},
  {PrimaryKey: 82095231, FreeText: 'Required by Support Team'},
];

/** One conflicting PK (24195339) plus one new PK (10270250) */
const apiStoredValues: FreeTextStoredValue[] = [
  {PrimaryKey: 24195339, FreeText: 'Updated by API'},
  {PrimaryKey: 10270250, FreeText: 'Added by API'},
];

function setOpsNoteValues(
  context: CustomToolbarButtonContext,
  replaceAction: 'All' | 'Conflicting' | 'None'
) {
  context.adaptableApi.freeTextColumnApi.setStoredValues(
    COLUMN_ID,
    apiStoredValues,
    replaceAction
  );
}

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'FreeText Column API',
  dashboardOptions: {
    customToolbars: [
      {
        name: 'FreeTextApi',
        title: 'Set Stored Values',
        toolbarButtons: [
          {
            label: 'None',
            onClick: (
              _button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => setOpsNoteValues(context, 'None'),
            buttonStyle: {tone: 'neutral', variant: 'outlined'},
          },
          {
            label: 'Conflicting',
            onClick: (
              _button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => setOpsNoteValues(context, 'Conflicting'),
            buttonStyle: {tone: 'info', variant: 'outlined'},
          },
          {
            label: 'All',
            onClick: (
              _button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => setOpsNoteValues(context, 'All'),
            buttonStyle: {tone: 'success', variant: 'outlined'},
          },
          {
            label: 'Reset',
            onClick: (
              _button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.freeTextColumnApi.setStoredValues(
                COLUMN_ID,
                initialStoredValues,
                'All'
              );
            },
            buttonStyle: {tone: 'error', variant: 'text'},
          },
        ],
      },
    ],
  },
  initialState: {
    Dashboard: {
      Tabs: [
        {
          Name: 'Demo',
          Toolbars: ['FreeTextApi'],
        },
      ],
    },
    FreeTextColumn: {
      FreeTextColumns: [
        {
          ColumnId: COLUMN_ID,
          FriendlyName: 'Ops Note',
          FreeTextStoredValues: initialStoredValues,
          FreeTextColumnSettings: {DataType: 'text', Resizable: true},
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'OpsNote',
            'language',
            'license',
            'github_stars',
            'github_watchers',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Read-only

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

PreviousFree Text Columns NextTechnical Reference