AdapTable Version:

Framework:

Free Text Columns

Summary

Free Text Columns allow run-time users to store custom data in AG Grid
Edits made in Free Text Columns are persisted in Adaptable State, rather than the Grid's Data Source
Each Free Text Column has a data type which can be Text, Numeric, Boolean or Date
It contains numerous other configurable properties e.g. width, filterable, groupable etc.
AdapTable will display a relevant cell editor when data is being added / edited in the Free Text Column

Free Text Columns are 'special columns' where users can write - and save - bespoke data.

This data is stored with the user's Adaptable State and is not persisted with the grid's data source.

Hint

The most common use case is to create 'Comment Columns' but any kind of bespoke data can be provided

Free Text Columns - like Calculated Columns and Action Columns - are not "normal" data columns; instead they are created dynamically by AdapTable each time the Application runs.

Note

Unlike Calculated Columns, Free Text Columns are always editable displaying a bespoke, rather than derived, value
Unlike Styled Columns, Free Text Column are special columns (and not specially rendered "normal" columns)

Each Free Text Column can be given a data-type, an optional default value, and pre-populated if required.

Caution

Free Text Columns are not available if you are using an auto-generated Primary Key

Free Text Columns

Fork Fork

This example provides 3 Free Text Columns (defined in Free Text Column Initial State):

Comments - a text column: 3 Stored Values provided, and set to be Resizable
Order Code - a number column: default value of 123 and the Menu suppressed
Is Used - a boolean column: default value of false and 4 Stored Values provided of true, and set to be Filterable

Expand to see the Free Text Column Definitions

FreeTextColumn: {
  FreeTextColumns: [
    {
      ColumnId: 'comments',
      FriendlyName: 'Comments',
      FreeTextStoredValues: [
        {PrimaryKey: 24195339, FreeText: 'Used by US team'},
        {PrimaryKey: 224663696, FreeText: 'My favourite'},
        {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,
      FreeTextStoredValues: [
        {PrimaryKey: 10270250, FreeText: true},
        {PrimaryKey: 24195339, FreeText: true},
        {PrimaryKey: 224663696, FreeText: true},
        {PrimaryKey: 82095231, FreeText: true},
      ],
      FreeTextColumnSettings: {
        DataType: 'boolean',
        Filterable: true,
        Groupable: true,
      },
    },
  ],
},

import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Free Text Column',
  initialState: {
    FreeTextColumn: {
      FreeTextColumns: [
        {
          ColumnId: 'comments',
          FriendlyName: 'Comments',
          FreeTextStoredValues: [
            {PrimaryKey: 24195339, FreeText: 'Used by US team'},
            {PrimaryKey: 224663696, FreeText: 'My favourite'},
            {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,
          FreeTextStoredValues: [
            {PrimaryKey: 10270250, FreeText: true},
            {PrimaryKey: 24195339, FreeText: true},
            {PrimaryKey: 224663696, FreeText: true},
            {PrimaryKey: 82095231, FreeText: true},
          ],
          FreeTextColumnSettings: {
            DataType: 'boolean',
            Filterable: true,
            Groupable: true,
          },
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'comments',
            'license',
            'orderCode',
            'language',
            'isUsed',
            'github_watchers',
            'week_issue_change',
            'github_stars',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'open_issues_count',
            'open_pr_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Deep Dive

How Free Text Columns Work in AdapTable

Free Text Column DataType

All Free Text Columns have a data type which defines what type of data the column can store.

Hint

The DataType property in FreeTextColumn can be set at run-time in the UI using the Free Text Column Wizard
Or provided at design time - it is the only mandatory property in FreeTextColumnSettings object

There are 4 possible values for the Data Type:

Note

AdapTable displays an appropriate cell editor based on the Column's DataType

text (the default value) - shows a standard text editor
number - displays the AdapTable Numeric Cell Editor
bBoolean - displays a checkbox
date - displays the AdapTable Date Picker

Hint

If no value is set then the default value of text is used

Default Value

Free Text Columns can be a given a default value.

This value be used automatically for every cell in the Column unless specifically overridden by the user.

Note

The default value is NOT stored in the FreeTextStoredValues property, along with hand-edited values
However it is rendered in the cell each time it is displayed in the UI

This option is available both when defining the column in Free Text Column Initial Adaptable State at design-time, and when creating it in the UI at run-time.

Caution

Make sure to provide a default value which is consistent with the DataType of the Column

Default and Pre-Stored Values

When defining Free Text Columns at design-time in Initial Adaptable State, it is possible to provide some initial cell values, using the the FreeTextStoredValues property.

These values will then display the first-time the Free Text Column is shown (and on all subsequent occasions unless they are overridden).

Note

You cannot supply Free Text Stored Values when creating the Free Text Column in the UI
But you can, of course, provide them subsequently simply by editing the cells

Formatted Free Text Columns

Free Text Columns, once created, are like any other Column and can be treated as such.

This means that they can be used with Column Formatting or as a Styled Column.

Free Text Columns Formatting

Fork Fork

This example provides 2 Free Text Columns which have been given additional formatting:

Last Spoken - a date column with 1 Stored Value (Note: a Date Picker appears when editing>) - we applied a Display Format
Status - a text column with 5 Stored Values: we applied a Badge Style and also limited the values that can be provided by using an Select Cell Editor

import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Free Text Column Formatted',
  editOptions: {
    showSelectCellEditor: context => {
      return context.column.columnId === 'status';
    },
    customEditColumnValues: context => {
      if (context.column.columnId === 'status') {
        return [
          {label: 'Preferred', value: 'Preferred'},
          {label: 'Allowed', value: 'Allowed'},
          {label: 'On-boarding', value: 'On-boarding'},
          {label: 'Not Allowed', value: 'Not Allowed'},
        ];
      }
      return context.defaultValues;
    },
  },
  initialState: {
    FreeTextColumn: {
      FreeTextColumns: [
        {
          ColumnId: 'lastSpoken',
          FriendlyName: 'Last Spoken',
          FreeTextStoredValues: [
            {PrimaryKey: 24195339, FreeText: new Date(2021, 5, 7)},
          ],
          FreeTextColumnSettings: {
            DataType: 'date',
          },
        },

        {
          ColumnId: 'status',
          FriendlyName: 'Status',
          FreeTextColumnSettings: {
            DataType: 'text',
          },
          FreeTextStoredValues: [
            {PrimaryKey: 10270250, FreeText: 'Preferred'},
            {PrimaryKey: 24195339, FreeText: 'Preferred'},
            {PrimaryKey: 74293321, FreeText: 'Allowed'},
            {PrimaryKey: 224663696, FreeText: 'On-boarding'},
            {PrimaryKey: 76694515, FreeText: 'Not Allowed'},
          ],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'license',
            'lastSpoken',
            'language',
            'status',
            'github_watchers',
            'github_stars',
            'week_issue_change',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'open_issues_count',
            'open_pr_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'formatColumn-lastSpoken',
          Scope: {ColumnIds: ['lastSpoken']},
          DisplayFormat: {
            Formatter: 'DateFormatter',
            Options: {
              Pattern: 'yyyy/MM/dd',
            },
          },
        },
      ],
    },
    StyledColumn: {
      StyledColumns: [
        {
          ColumnId: 'status',
          BadgeStyle: {
            Badges: [
              {
                Predicate: {
                  PredicateId: 'Is',
                  Inputs: ['Preferred'],
                },
                Style: {
                  BackColor: 'Green',
                  ForeColor: 'White',
                  BorderRadius: 6,
                },
              },
              {
                Predicate: {
                  PredicateId: 'In',
                  Inputs: ['Allowed', 'On-boarding'],
                },
                Style: {
                  BackColor: 'Orange',
                  ForeColor: 'White',
                  BorderRadius: 6,
                },
              },
              {
                Predicate: {
                  PredicateId: 'Is',
                  Inputs: ['Not Allowed'],
                },
                Style: {
                  BackColor: 'Red',
                  ForeColor: 'White',
                  BorderRadius: 6,
                },
              },
            ],
          },
        },
      ],
    },
  },
};

Using Free Text Columns

Run-time access to Free Text Columns is available in the Free Text Column section of the Settings Panel.

Note

There is no Free Text Column Toolbar or Tool Panel

This displays a list of existing Free Text Columns with buttons to edit, share or delete each item.

Caution

Free Text Columns cannot be suspended
AdapTable will try to prevent you from deleting a Free Text Column which is referenced elsewhere

There is also an Add button to create new Free Text Columns using the Free Text Column Wizard.

Note

Newly created Free Text Columns are automatically added to the end of the Current Layout
Existing Free Text Columns include an Edit Free Text Column Menu Item in the Column Menu

UI Step by Step Guide

Using the Free Text Column Wizard

UI Entitlements

The UI Entitlements behaviour for Free Text Columns is as expected for Full and Hidden Access Levels.

The ReadOnly Entitlement behaviour is that the Column will be displayed but Users are not permitted to edit or delete its configuration.

Caution

If you are using an auto-generated Primary Key then Free Text Columns will never be available

Free Text Columns

(Recorded with AdapTable v14.0)

FAQ

Where is the data stored for Free Text Columns? With the User's Adaptable State wherever that is stored, i.e. locally or remotely. Free Text Column data is not stored with the dataset of the underlying grid.

Why can't I see my Free Text Columns or the Free Text Column Settings Panel? Check if you are using an auto-generated Primary Key; if so then Free Text Columns are unvailable as they require a Primary Key that is guaranteed to be consistent between sessions

Can we refer to the Free Text Column in our AG Grid Column Definitions (e.g. to put it in a Column Group)? Yes, you can do that. You must ensure the colId matches the Free Text Column columnID and to add a Column Type of freeTextColumn

If I provide a Shortcut for numeric data entry, is this available in Free Text Columns? Yes, Shortcuts will work anywhere where the numeric editor is used, including in numeric Free Text Columns (which have the correct scope)

Where is my newly created Free Text Column? Free Text Columns added through the Free Text Column Wizard get added to the end of the Current Layout. If provided through Initial Adaptable State, they will need to be explicitly added to the relevant Layout.

PreviousTechnical Reference NextConfiguring Free Text Columns