Editing in AdapTable

Editing Data in AdapTable (v22)

This blog post illustrates how AdapTable facilitates swift and safe data entry.

It is based around a small demo that contains many of the editing-related features and functionalities provided in AdapTable including:

Important

The demo uses only existing AdapTable functionality, UI components and API methods

Functionality	Details
Smart Edit	Edits multiple numeric cells using single operation
Bulk Update	Updates many cells to same value
Shortcut	Sets mathematical operations when shortcut key is clicked
Plus Minus	"Nudge Rules" for when + or - are pressed on the keyboard
Cell Editors	Specialist Editors - Select, Percent, Numeric & Date Picker
Action Column	Special columns containing buttons (which can be used when editing)
Row Forms	Special forms designed for bespoke row editing (and creating)
Cell Editability	Configure which cells can be edited
Editable Cell Styling	Custom style Editable, ReadOnly and Edited Cells
Data Validation	Validate data entry (on both Client and Server)
Change History	Full recorded history of all data edits

Smart Edit

The Smart Edit module allows users to apply a single edit to multiple, numeric cells, using one of the 4 mathematical Smart Edit Operations supplied by AdapTable:

Addition
Subtraction
Multiplication
Division

In addition developers are able to provide Custom Smart Edit Operations if required.

We do that in this demo by providing a Power operation:

editOptions: {
  smartEditCustomOperations: [
  {
    name: 'Power',
    operation: (context: SmartEditOperationContext) => {
      return Math.pow(context.currentCell.rawValue, context.smartEditValue);
    },
  }],
}

We leverage the Adaptable Ready Event - which fires when AdapTable has initialised - to make Power the current operation and to set the smart edit value to 2:

export const onAdaptableReady = ({adaptableApi}: AdaptableReadyInfo) => {
  adaptableApi.smartEditApi.setCustomSmartEditOperation('Power');
  adaptableApi.smartEditApi.setSmartEditValue(2);
};

Bulk Update

AdapTable also provides a Bulk Update module which facilitates updating multiple cells in one step to the same value.

Note

Bullk Update controls display a dropdown listing all distinct column values to facilitate quick editing
Alternatively, users can provide a new value which is not currently in the Grid

Shortcut

Another data entry Module provided by AdapTable is Shortcuts.

Hint

Shortcuts help to avoid "fat finger" issues by providing an easy way to accurately edit numeric data

A Shortcut consists of an alphabet keystroke which when entered into a numeric cell automatically converts into a mathemetical operation using the existing cell contents.

In our Demo we added a Shortcut of 'K' multiplying values in Github Watchers column by 1000:

Shortcut: {
  Shortcuts: [
    {
      Name: 'shortcut-K-multiply-1000',
      Scope: { ColumnIds: ['github_watchers'] },
      ShortcutKey: 'K',
      ShortcutOperation: 'Multiply',
      ShortcutValue: 1000,
    }],
},

Plus Minus

The Plus Minus module is used to update numeric cells in response to keyboard input:

the plus keyboard key causes an increment of the cell's value
the minus keyboard key causes a decrement of the cell's value

Hint

This is ideal for situations where data needs to be edited incredibly quickly (e.g. if marking to market)

In our demo we have applied 2 Plus Minus Nudge Rules to the Github Stars column:

Note

One Plus Minus Nudge contains a condition, so the Nudge only applies where the rule returns true
The other Nudge has no condition so is applied in all rows where the Conditional Nudge is inactive

PlusMinus: {
  PlusMinusNudges: [
    {
      Name: 'plusMinus-github_stars-TypeScript',
      Scope: { ColumnIds: ['github_stars'] },
      Rule: { BooleanExpression: '[language] = "TypeScript"' },
      NudgeValue: 10,
    },
    {
      Name: 'plusMinus-github_stars-Normal',
      Scope: { ColumnIds: ['github_stars'] },
      NudgeValue: 2,
    }],
},

Action Column

The functionality we provide in the Plus Minus rules for the Github Stars can also be achieved using Action Columns.

Action Columns are special columns which display a Button(s) with a user-defined action.

Hint

The buttons can do anything but one frequent use case is to edit a cell in an adjacent Column

Our demo contains an Update Stars Action Column which contains Up and Down buttons that update the Github Stars column (using same rules as provided for Plus Minus Nudges above).

actionColumnOptions: {
  actionColumns: [
    {
      columnId: 'update_stars',
      friendlyName: 'Update Stars',
      actionColumnButton: [
        {
          label: 'Up',
          buttonStyle: { variant: 'outlined', tone: 'info' },
          onClick: (button: ActionColumnButton<ActionColumnContext>, context: ActionColumnContext) => {
            const rowData: WebFramework = context.rowNode?.data;
            const increment = rowData.language == 'TypeScript' ? 10 : 2;
            const cellUpdateRequest: CellUpdateRequest = {
              columnId: 'github_stars',
              newValue: rowData.github_stars + increment,
              primaryKeyValue: context.primaryKeyValue,
              rowNode: context.rowNode,
            };
            context.adaptableApi.gridApi.setCellValue(cellUpdateRequest);
          },
        },
        {
          label: 'Down',
          buttonStyle: { variant: 'outlined', tone: 'warning' },
          onClick: ( button: ActionColumnButton<ActionColumnContext>, context: ActionColumnContext) => {
            const rowData: WebFramework = context.rowNode?.data;
            const increment = rowData.language == 'TypeScript' ? 10 : 2;
            const cellUpdateRequest: CellUpdateRequest = {
              columnId: 'github_stars',
              newValue: rowData.github_stars - increment,
              primaryKeyValue: context.primaryKeyValue,
              rowNode: context.rowNode,
            };
            context.adaptableApi.gridApi.setCellValue(cellUpdateRequest);
          },
        }],
    },],
},

Cell Editors

AdapTable provides 4 Cell Editors so that data can can be quickly and safely entered into AG Grid:

Editor	Which Columns	When Used
Select (Dropdown) Editor	All	If configured
Numeric Cell Editor	Numeric	Always
Date Picker	Date	Always
Percentage Cell Editor	Numeric	With % Rendering

In the demo we display the Select Editor when editing the Language and License columns:

editOptions: {
  showSelectCellEditor: context => {
    return (context.column.columnId === 'language' || context.column.columnId === 'license');
  },
}

Note

The Numeric Cell Editor and Date Picker are also available in the demo as they are the default editors

Custom Edit Values

By default the Select Editor will display all the distinct values in the Column, and the run-time user simply needs to select the required value from the list that automatically appears.

However it is possible to provide a custom set of values to display in the select editor if required.

In the demo we provide extra options to display in the Language Column's Select Editor:

editOptions: {
  customEditColumnValues: (customEditColumnValuesContext: CustomEditColumnValuesContext) => {
    if (customEditColumnValuesContext.column.columnId === 'language') {
      return [
        ...customEditColumnValuesContext.defaultValues,
        {label: 'Python', value: 'Python'},
        {label: 'XML', value: 'XML'},
        {label: 'CSS', value: 'CSS'},
      ];
    }
    return customEditColumnValuesContext.defaultValues;
  },
}

Note

The additional Language Column options are also available when using Bulk Update components
Likewise, you will see these values when editing the Column in a Row Form (see below)

Row Forms

AdapTable provides Row Forms as an alternative to inline data editing.

Row Forms are popups which display all editable fields in a row, togther with the appropriate cell editor for that field.

Hint

Row Forms are useful if wanting to perform particular actions or validation before committing edits
They also allow users to batch all the edits for a row into a single update action

Our demo includes an Edit Row Form, which is accessed via an edit Action Column Command.

actionColumnOptions: {
  actionColumns: [
    {
      columnId: 'edit',
      friendlyName: 'Actions',
      actionColumnButton: [
        {
          command: 'edit',
          label: ' Edit',
          buttonStyle: { variant: 'text', tone: 'success' },
        },
      ],
    },
  ],
},

The configuration for the Row Form sets 3 things:

auto-handles saving the Row (there is an option to handle the Save in a custom fashion)
we dont disable in line editing (normally set to true but we want to show both in our demo)
hides the id Column from the Row Form (as the user doesn't need to see it)

rowFormOptions: {
  autoHandle: true,
  disableInlineEditing: false,
  includeColumnInRowForm: (rowFormColumnContext: RowFormColumnContext) => {
    return rowFormColumnContext.adaptableColumn.columnId !== 'id';
  },
},

Setting Cell Editability

AdapTable respects AG Grid rules regarding whether cells are editable or readonly.

But it also allows developers to override this and set editability at Column or Cell level.

In our demo we have set the Language and Issue Change Columns to be readonly, but provide exceptions where Language is not "HTML" and Issue Change is positive.

editOptions: {
  isCellEditable: (cellEditableContext: CellEditableContext) => {
    const gridCell: GridCell = cellEditableContext.gridCell;
    if (gridCell.column.columnId === 'language' && gridCell.displayValue !== 'HTML') {
      return true;
    }
    if (gridCell.column.columnId === 'week_issue_change' && gridCell.rawValue > 0) {
      return true;
    }
    return cellEditableContext.defaultColDefEditableValue;
  },
},

Styling Editable Cells

AdapTable allows developers to visually indicate cell editability information to runtime users.

There are 3 similar functions which allow styles to be provided for:

editable Cells
readonly Cells
edited Cells

In our demo we provide 2 Styles: one for editable Cells, and one for edited Cells:

  userInterfaceOptions: {
    editableCellStyle: {
      BorderColor: 'LightYellow',
      BorderRadius: 6,
    },
    editedCellStyle: {
      BackColor: 'LightYellow',
      ForeColor: 'Brown',
    },
  },

Validation

AdapTable providdes 2 main types of Data Validation:

Client Validation - Undoes an Edit that breaks a Rule (leveraging a Validation Alert)
Server Validation - Checks Validation on the Server and returns a result

In our demo we provide one example of each Validation, using the Issue Change Column:

Client Side Validation - cannot be negative (if so, then a warning appears)

Alert: {
  AlertDefinitions: [
    {
      Name: 'alert-week_issue_change_negative',
      Scope: { ColumnIds: ['week_issue_change'] },
      Rule: { Predicates: [{ PredicateId: 'Negative' }]},
      AlertProperties: {
        PreventEdit: true,
        DisplayNotification: true,
      },
      MessageType: 'Error',
      MessageText: 'Week Issue Change cannot be negative!',
    },
  ],
},

Server Side Validation - value cannot be greater than 60 (if so, then we set to 60)

editOptions: {
  validateOnServer: (serverValidationContext: ServerValidationContext) => {
    return new Promise((resolve, reject) => {
      // would typically happen on the server, rather than client...
      const cellDataChangedInfo = serverValidationContext.cellDataChangedInfo;
      if (cellDataChangedInfo.column.columnId == 'week_issue_change') {
        if (cellDataChangedInfo.newValue > 60) {
          resolve({
            newCellValue: 60,
            validationMessage: 'Week Issue Change cannot be greater than 60',
            validationHeader: 'Too High',
            messageType: 'Error',
          });
          return;
        }
      }
      resolve({});
    });
  },
},

Data Change History

AdapTable can display a list of all data changes that have happened in the current session.

In our demo we have set the (very configurable) Data Change History Monitor to:

be turned on by default (so all data changes are automatically tracked)
provided with an "undo" button which, when clicked, will undo the change

dataChangeHistoryOptions: {
  activeByDefault: true,
  changeHistoryButton: [
    {
      action: 'undo',
      label: (button, context) => { return context.isGroupNode ? 'Undo Group' : 'Undo';  },
      buttonStyle: { variant: 'raised', tone: 'accent' },
    },
  ],
},

Important

Smart Edit

Bulk Update

Note

Shortcut

Hint

Plus Minus

Hint

Note

Action Column

Hint

Cell Editors

Note

Custom Edit Values

Note

Row Forms

Hint

Setting Cell Editability

Styling Editable Cells

Validation

Data Change History

AdapTable Resources