Free Text Column Module

The FreeText Column Module enables the creation of 'special columns' for users to save comments and other data that will not be persisted with the grid's data source, but in Adaptable State instead.

FreeText Columns are similar to Calculated Columns; they are not part of AG Grid's Column Definitions but are defined and stored in Adaptable State, and recreated each time the Application starts.

note

The difference with Calculated Column is that a FreeText Column is designed to be editable (not derived) - the purpose is for users to store whatever bespoke data they want for each row.

Column DataType

FreeText Columns have a DataType property which defines what type of data the column can store.

There are 4 possible values, each of which will result in a different cell editor being displayed:

  • String (the default value) - shows a standard text editor
  • Number - displays the AdapTable numeric editor
  • Boolean - displays a checkbox
  • Date - displays the AdapTable date picker
tip

If no value is set then the default of 'string' is used

When editing in the FreeText Column, AdapTable will automatically display an appropriate for its DataType (e.g. a date picker for 'Date').

note

If the DataType is string, there is an extra choice that can be made: TextEditor lets you pick between 'Inline' (the default) or 'Large' (useful if wanting to provide large quantities of text).

Stored Values

The FreeText Column stores any values which have been provided in the FreeTextStoredValues property.

The FreeTextStoredValue object is straightforward, allowing users to store values by primary key:

PropertyDescription
FreeTextValue to store in the cell
PrimaryKeyPrimary Key Column value for the row
tip

This can be set at Design Time so that a FreeText Column can be 'pre-populated' with relevant values

Default Value

FreeText Columns have an optional default value; if provided, the cell will display that value unless explicitly overriden by the User.

UI Elements

FreeText Column includes the following UI Elements:

  • Popup - Shows a list of existing FreeText Columns with Edit and Delete buttons. Plus an Add button to start the FreeText Column Wizard which facilitates the creation and editing of Free Text Columns. Each row in the popup is fully editable.

  • Column Menu - Existing FreeText columns have a Edit Free Text Column Menu Item which opens the Format Column wizard for that Column.

UI Entitlements

UI Entitlements behaviour is as expected for Full and Hidden Access Levels.

The ReadOnly Entitlement behaviour is that FreeText Columns can be added / removed from Layouts and visible in the Grid but Users cannot manage or suspend them.

note

FreeText Columns can still be edited (ie have new values entered into the cells in the Column) while in ReadOnly mode even though, technically, this does update the underlying object

Adding Stored Values

There are a few different methods to allow you to add Stored Values to a FreeText Column which cater for different use cases.

The most commonly used, and useful, of these functions is addStoredValuesToFreeTextColumn.

It receives a ColumnId, a list of Stored Values and a replaceAction property which can be one of 3 values:

  • All - replaces ALL existing Stored Values for the Column with the new ones even if there are no clashes
  • Conflicting - adds all given stored values and replaces any existing ones which clash with the new set
  • None - only adds the stored values where there are no existing entries with the same primary key

Free Text Column API Methods

MethodDescription
addEditFreeTextColumnStoredValue(freeTextColumn, storedValue)Adds FreeTextStoredValue for a FreeTextColumn (replaces existing one if exists)
addFreeTextColumn(freeTextColumn)Adds new FreeTextColumn to Adaptable State
addStoredValuesToFreeTextColumn(columnId, storedValues, replaceAction)Adds Stored Values to Existing FreeTextColumn
checkFreeTextColumnForDataChange(dataChangedInfo)Checks if a User Edit was in a Free Text Column
createFreeTextColumn(param)Creates new FreeTextColumn and adds it to Adaptable State
deleteFreeTextColumn(columnId)Deletes existing FreeTextColumn from Adaptable State
editFreeTextColumn(freeTextColumn)Edits existing FreeTextColumn in Adaptable State
getAllFreeTextColumn()Gets all FreeTextColumns in Adaptable State
getFreeTextColumnById(columnId)Retrieves FreeTextColumn for given ColumnId
getFreeTextColumnModuleReferences(freeTextColumn)Returns all the references in the AdaptableState of the given FreeTextColumn
getFreeTextColumnState()Retrieves FreeTextColumn section of Adaptable State
getFreeTextColumnValueFromRowNode(freeTextColumn, rowNode)Retrieves a Free Text Column value from a row
showFreeTextColumnPopup()Opens FreeTextColumn popup screen

See API documentation for full details of all available functions with lists of parameters

Free Text Column Predefined Config

The Free Text Column State contains a collection of FreeTextColumn objects:

PropertyDescription
FreeTextColumnsCollection of Free Text Columns

Free Text Column Object

A FreeTextColumn object is defined as follows:

PropertyDescriptionDefault
ColumnIdId of Column
DataTypeWhether Column is String, Number, Boolean or Date; the appropriate Cell Editor will be used'String'
DefaultValueInitial value to use for each cell in the Column
FreeTextColumnSettingsAdditional optional properties for Column (e.g. filterable, resizable)
FreeTextStoredValuesCollection of Stored Values to aplly in the Column
FriendlyNameFriendly Name to use to refer to Column; if unset ColumnId is used
TextEditorCell editor to use when editing a Free Text Column with DataType of 'String' *'Inline'

Free Text Column Stored Value

The FreeTextColumn object includes a FreeTextStoredValues property which is defined as follows:

tip

Free Text Stored Values will typically be added by users at run-time, rather than set at design-time

PropertyDescription
FreeTextValue to store in the cell
PrimaryKeyPrimary Key Column value for the row

Putting it Together

const demoConfig: PredefinedConfig = {
FreeTextColumn: {
FreeTextColumns: [
{
ColumnId: 'Comments',
FriendlyName: 'User Comments',
DefaultValue: '',
FreeTextStoredValues: [
{ PrimaryKey: 11137, FreeText: 'Dispatch asap' },
{ PrimaryKey: 11133, FreeText: 'Angry customer' },
{ PrimaryKey: 11128, FreeText: 'Important order' },
],
},
],
},
} as PredefinedConfig;

FAQ

Where is the data stored for Free Text Columns?

With the User's Adaptable State wherever that is stored. Free Text Column data is not stored with the dataset of the underlying grid.

More Information