Data Entry

Editing Technical Reference

View as Markdown

Adaptable Options

Edit Options

EditOptions

Options related to Editing in AdapTable - includes Server Validation, Smart Edit Operations and Cell Editabiility

customEditColumnValues?

(context:CustomEditColumnValuesContext<TData>) =>CustomEditColumnValueInfo[] | Promise<CustomEditColumnValueInfo[]>

List of Column values to display when Editing (i.e. in Edit Lookups, Bulk Update)

displayServerValidationMessages?

boolean

Whether to display message after Server Validation runs

Default

true

isCellEditable?

(cellEditableContext:CellEditableContext<TData>) => boolean

Function which checks if a given Grid Cell is editable

plusMinusOptions?

PlusMinusOptions

Keys that nudge a numeric cell up or down.

A Plus Minus rule can set its own key. These are the keys used when it does not.

showSelectCellEditor?

(currentColumContext:AdaptableColumnContext<TData>) => boolean

Columns that will display a Select dropdown when editing

smartEditOptions?

SmartEditOptions<TData>

Extra Smart Edit operations, beyond the ones AdapTable ships.

A Smart Edit applies one operation to every selected cell.

validateOnServer?

(serverValidationContext:ServerValidationContext<TData>) => Promise<ServerValidationResult>

Function to validate AdapTable data edits remotely

isCellEditable receives a CellEditableContext:

customEditColumnValues receives a CustomEditColumnValuesContext and returns CustomEditColumnValueInfo objects:

CustomEditColumnValueInfo

Information about items in the custom Edit Controls

label?

string

Text shown for this item. The value is shown when this is omitted.

value

any

Value written into the cell when this item is chosen.

validateOnServer receives a ServerValidationContext and returns a ServerValidationResult:

Smart Edit Options

A custom operation is { name: string; operation: (context) => number }. The operation receives a SmartEditOperationContext:

Plus Minus Options

PlusMinusOptions

Options for editing-based Plus Minus Module

decrementKey?

string

Key to decrease cell value for nudges (if not overriden in Plus Minus Rule/Nudge).

Can be a single key (e.g. '-') or a keyboard shortcut combination that uses
+ as the glue between parts (e.g. 'shift+Backspace', 'ctrl+ArrowDown').
Supported modifiers are ctrl, cmd, alt and shift.

Default

'-'

incrementKey?

string

Key to increase cell value for nudges (if not overriden in Plus Minus Rule/Nudge).

Can be a single key (e.g. '+') or a keyboard shortcut combination that uses
+ as the glue between parts (e.g. 'shift+Enter', 'ctrl+ArrowUp').
Supported modifiers are ctrl, cmd, alt and shift.

Default

'+'

Adaptable State

Plus Minus State

PlusMinusState

Plus Minus section of Adaptable State, including Initial State.

Each nudge adds or subtracts NudgeValue from numeric cells in Scope. The increment key adds NudgeValue; the decrement key subtracts it. A nudge's own keys override plusMinusOptions, which override the default + and - keys.

Extends

BaseState

PlusMinusNudges?

PlusMinusNudge[]

Nudges to apply. Each one names numeric columns, the amount, and optional keys.

Plus Minus

PlusMinusNudge

Adds or subtracts a fixed amount from numeric cells.

Scope is numeric columns only. The increment key sets the cell to its current value plus NudgeValue; the decrement key subtracts NudgeValue. Omit Rule to apply the nudge on every row in scope. Suspend with IsSuspended.

Extends

SuspendableObject

DecrementKey?

string

Optional keyboard key that decreases cell values for this nudge only (overrides the
global decrementKey in plusMinusOptions).

Can be a single key (e.g. '-') or a keyboard shortcut combination that uses + as the glue
between parts (e.g. 'shift+Backspace', 'ctrl+ArrowDown'). Supported modifiers are ctrl,
cmd, alt and shift.

IncrementKey?

string

Optional keyboard key that increases cell values for this nudge only (overrides the
global incrementKey in plusMinusOptions).

Can be a single key (e.g. '+') or a keyboard shortcut combination that uses + as the glue
between parts (e.g. 'shift+Enter', 'ctrl+ArrowUp'). Supported modifiers are ctrl, cmd,
alt and shift.

Name

string

Name of the Plus Minus Nudge rule

NudgeValue

number

Amount added by the increment key and subtracted by the decrement key.

Rule?

string

(Optional) AdapTableQL boolean expression, evaluated per row, to determine whether to apply the Nudge

Scope

ColumnScope<NumberScopeDataType>

Numeric columns where the nudge is applied

IsReadOnly?

boolean

Sets Entity to ReadOnly (overwriting a Strategy Entitlement of 'Full')

IsSuspended?

boolean

Suspends (i.e. turns off) an Adaptable Object

Scope

ColumnScope

Which columns an object applies to. Set exactly one shape.

One of
{ All: true }

true

Matches every column. All must be true.

{ DataTypes }

('text' | 'number' | 'boolean' | 'date' | 'textArray' | 'numberArray')[]

Data types to match, for example ['number'] or ['text', 'textArray']. Object, tuple and unknown columns are not scope data types. Name those columns with ColumnIds.

{ ColumnIds }

string[]

Column ids to match. These are AG Grid colId values.

{ ColumnTypes }

string[]

AG Grid column type names, the strings set on colDef.type.

Shortcut State

ShortcutState

Shortcut section of Adaptable State, including Initial State.

Each shortcut updates a numeric cell while its editor is open and ShortcutKey is pressed. The cell value is the first operand and ShortcutValue is the second. ShortcutOperation is 'Add', 'Subtract', 'Multiply' or 'Divide'. The first shortcut whose key and scope match is used. A ShortcutValue of 0 is ignored.

Extends

BaseState

Shortcuts?

Shortcut[]

Shortcuts to apply. Each one names numeric columns, a key, an operation and the second operand.

Shortcut Object

Shortcut

A key that updates a numeric cell with an arithmetic operation.

Scope is numeric columns only. Pressing ShortcutKey sets the cell to cellValue combined with ShortcutValue by ShortcutOperation. Suspend with IsSuspended.

Extends

SuspendableObject

Name

string

Name of the Shortcut

Scope

ColumnScope<NumberScopeDataType>

Numeric Columns where Shortcut is applied

ShortcutKey

string

Key which triggers the Shortcut when pressed

ShortcutOperation

'Add' | 'Subtract' | 'Multiply' | 'Divide'

The Operation: 'Add', 'Subtract', 'Multiply', 'Divide'

ShortcutValue

number

Value acting as 2nd operand for ShortcutOperation (1st operand is the cell value)

IsReadOnly?

boolean

Sets Entity to ReadOnly (overwriting a Strategy Entitlement of 'Full')

IsSuspended?

boolean

Suspends (i.e. turns off) an Adaptable Object

Scope

Scope is a Column Scope object but limited to numeric columns:

ColumnScope

Which columns an object applies to. Set exactly one shape.

One of
{ All: true }

true

Matches every column. All must be true.

{ DataTypes }

('text' | 'number' | 'boolean' | 'date' | 'textArray' | 'numberArray')[]

Data types to match, for example ['number'] or ['text', 'textArray']. Object, tuple and unknown columns are not scope data types. Name those columns with ColumnIds.

{ ColumnIds }

string[]

Column ids to match. These are AG Grid colId values.

{ ColumnTypes }

string[]

AG Grid column type names, the strings set on colDef.type.

Adaptable API

Smart Edit API

SmartEditApi

Smart Edit: one change applied to every selected cell.

getSmartEditCustomOperations()
returns

SmartEditCustomOperation[]

Retrieves an Smart Edit Custom Operations (provided in Edit Options)

getSmartEditOperation()
returns

SmartEditOperation

Gets current Smart Edit Operation

getSmartEditValue()
returns

number

Returns current Smart Edit Value

openSmartEditSettingsPanel()
returns

void

Opens Settings Panel with Smart Edit section selected and visible

setCustomSmartEditOperation(customOperationName)
returns

void

Sets current Smart Edit Operation to a Custom Operation

setSmartEditOperation(operation)
returns

void

Sets (shipped) Smart Edit Operation: 'Add','Subtract','Multiply','Divide'

setSmartEditValue(smartEditValue)
returns

void

Sets Smart Edit Value

Bulk Update API

Plus Minus API

PlusMinusApi

Plus Minus nudges that change a numeric cell by a configured amount.

addPlusMinusNudge(plusMinusNudge)
returns

PlusMinusNudge

Adds new Plus Minus Rule to State

applyPlusMinus(cellUpdateRequests)
returns

void

Applies a Plus Minus to given cells

deletePlusMinusNudge(plusMinusNudge)
returns

void

Deletes a plus minus rule

editPlusMinusNudge(plusMinusNudge)
returns

PlusMinusNudge

Replaces Plus Minus Rule in State with given one

getAllActivePlusMinus()
returns

PlusMinusNudge[]

Retrieves all active (not-suspended) Plus Minus Rules in Adaptable State with those with expressions first

getAllPlusMinus()
returns

PlusMinusNudge[]

Retrieves all Plus Minus Rules in Adaptable State with those with expressions first

getAllSuspendedPlusMinus()
returns

PlusMinusNudge[]

Retrieves all suspended Plus Minus Rules in Adaptable State with those with expressions first

getPlusMinusById(id)
returns

PlusMinusNudge

Retrieves Plus Minus Rule by the technical ID (from PlusMinusState)

getPlusMinusNudgeByName(name)
returns

PlusMinusNudge | undefined

Retrieves a Plus Minus Nudge by its Name

getPlusMinusState()
returns

PlusMinusState

Retrieves Plus Minus section from Adaptable State (nudge rules only).
Keyboard triggers are optional on each ; unset fields fall back to
AdaptableOptions.plusMinusOptions, then + / -.

openPlusMinusSettingsPanel()
returns

void

Opens Settings Panel with Plus Minus section selected and visible

runPlusMinusNudge(plusMinusNudge, cells, direction)
returns

void

Applies a Plus Minus Rule to given cells

unSuspendPlusMinusNudge(plusMinusNudge)
returns

PlusMinusNudge

Activates a suspended Plus Minus Rule

Shortcut API

ShortcutApi

Keyboard shortcuts that change a cell value.

addShortcut(shortcut)
returns

Shortcut

Adds new Shortcut to the state

deleteShortcut(shortcut)
returns

void

Deletes Shortcut from the state

editShortcut(shortcut)
returns

Shortcut

Edits Shortcut in state

getActiveShortcuts()
returns

Shortcut[]

Gets all active (not-suspended) Shortcuts in Adaptable State

getShortcutById(id)
returns

Shortcut

Retrieves Shortcut by Id

getShortcutByName(name)
returns

Shortcut | undefined

Retrieves a Shortcut by its Name

getShortcuts()
returns

Shortcut[]

Gets all Shortcuts in Adaptable State

getShortcutState()
returns

ShortcutState

Retrieves Shortcut section from Adaptable State

getSuspendedShortcuts()
returns

Shortcut[]

Gets all suspended Shortcuts in Adaptable State

openShortcutSettingsPanel()
returns

void

Opens Settings Panel with Shortcut section selected and visible

suspendAllShortcut()
returns

void

Suspends all Shortcuts

suspendShortcut(shortcut)
returns

Shortcut

Suspends Shortcut definition

unSuspendAllShortcut()
returns

void

Activates all suspended Shortcut

unSuspendShortcut(shortcut)
returns

Shortcut

Activates a suspended Shortcut definition

Cell Changed Event

The Cell Changed Event fires whenever the contents of any cell changes in AG Grid.

This can be the result of a user cell edit or of ticking data.

CellChangedInfo

The event comprises the CellChangedInfo object:

CellChangedInfo

Payload of the CellChanged event.

Fires when a cell value changes: an edit, a tick, an undo, an aggregation change, or a Calculated Column update. A live Alert rule does not fire this event; it fires AlertFired.

Extends , so adaptableApi is included.

Extends

BaseContext

cellDataChange

CellDataChangedInfo

The change: old and new values, column, row and what triggered it. See .

adaptableContext

any

Custom application Context provided in AdaptableOptions.adaptableContext

This provides a single cellChange property of type CellDataChangedInfo defined as follows:

CellDataChangedInfo

Defines a Cell Edit - includes full details of old and new values, the column and the enclosing Row

changedAt

number

Timestamp of change occurrence (in milliseconds)

column

AdaptableColumn<TData>

Column in which cell is situated

newValue

any

Value after the change.

Absent when trigger is live.

oldValue

any

Value before the change.

Absent when trigger is live.

preventEdit?

boolean

Whether the change was prevented by a validation rule

primaryKeyValue

any

Primary Key Column's value for the row where edited cell is situated

rowData?

TData

Data in the Row

rowNode?

IRowNode<TData>

AG Grid RowNode that contains the cell

trigger?

'edit' | 'tick' | 'undo' | 'aggChange' | 'calculatedColumnChange' | 'live'

What triggered the change - user, background change, a reverted change, a
derived update on a Calculated Column whose source value changed, or a
live Alert rule turning true for the row (live: no old / new value,
column is the rule's first Scope column when it has one).

Event Subscription

Subscribing to the Event is done the same way as with all Adaptable Events:

api.eventApi.on('CellChanged', (eventInfo: CellChangedInfo) => {
    // do something with the info
});

Find Out More

See Listening to Cell and Row Changes for a worked example

PreviousCustom Edit ValuesNextCell Editors