AdapTable Version:

Framework:

Server Data Validation

Summary

Server-side validation can be used to validate (and undo) Edits via a function
An optional Message can be displayed to the User

AdapTable provides Server Validation, i.e. validation through a function provided by the user.

Find Out More

AdapTable also offers Client Validation where the validation is handled using Validation Alerts

This is available via the validateOnServer property in Edit Options.

If provided, the async function will be invoked by AdapTable each time a cell is edited.

Caution

This function will only be called after Client Validation has successfully completed

The function receives as an argument full details of the proposed edit and returns one of 3 values:

nothing - either the edit is valid, or it will be updated via the API or an alternate mechanism
the old value - i.e. validation failed so we should return the cell to it's previous value
a different value - often used if new value breaches upper or lower limits bounds (see example below)

validateOnServer

Runs Validation of Data Edits on the Server

validateOnServer?: (serverValidationContext: ServerValidationContext) => Promise<ServerValidationResult>;

ServerValidationContext

The function receives a ServerValidationContext object which wraps a CellDataChangedInfo object.

This provides details of the old and new cell values, the cell's containing column and the relevant row node.

Property	Description
changedAt	Timestamp of change occurrence (in milliseconds)
column	Column in which cell is situated
newValue	New value for the cell
oldValue	Value in the Cell before the edit
primaryKeyValue	Primary Key Column's value for the row where edited cell is situated
rowData	Data in the Row
rowNode	AG Grid RowNode that contains the cell
trigger	What triggered the change - user, background change or a reverted change?

ServerValidationResult

The function returns a Promise containing a ServerValidationResultobject:

Property	Description	Default
messageType	Type of Message to Display	Info
newCellValue	Cell Value to use for after Server Validation
validationHeader	Header to diplay with validation	'Server Validation Message',
validationMessage	Message to diplay with validation

The newCellValue property in this object is the value to use in the cell instead of the one proposed by the Cell Edit.

It can be one of 3 possibilities:

nothing - the edit is valid, or you want to 'swallow' it and update the data via the API or an alternate mechanism
the old value - i.e. validation failed so we should return to the previous cell value

Hint

You can retrieve the previous value through the oldValue property of CellDataChangedInfo

a different value altogether - this is rare but sometimes used in advanced scenarios

The object also contains 3 optional properties, used to configure the ValidationMessage displayed to the User:

Note

This Notification Message is displayed in addition to allowing / cancelling the Edit

validationMessage - the text of the Message
validationHeader - the header of the Message
messageType - The type of the Message (of type MessageType)

Caution

Th Notifcation will only appear if displayServerValidationMessages is set to true in Edit Options

Validation Message

Additionally, AdapTable can display a Notification to the user regarding the outcome of the Validation.

This is done via 3 optional properties provided in the ServerValidationResultobject returned by the function.

Note

This Notification Message is displayed in addition to allowing / cancelling the Edit

The 3 properties which can be returned are:

Property	Description	Behaviour if not supplied
`validationHeader`	Header of the Message	Header is "Server Validation Message"
`validationMessage`	Text of the Message	No Notification is displayed
`messageType`	Defines the `MessageType` to use	Uses default of Info

Hint

The Notification behaviour (e.g. location, duration etc.) will be based on the settings in Notification Options

The Message only displays if displayServerValidationMessages in Edit Options is set to true (the default value).

displayServerValidationMessages

Default: true

boolean

Displays a Notification Message after Server Validation

If true, an Info Message appears with ValidationMessage sent by ServerValidation.

editOptions: {
  // Don't allow any Server Validation Messages to be displayed
  displayServerValidationMessages: false
},

Note

If validateOnServer function returns no Validation Message, no message is displayed if even this value is true

Server Validation

Fork Fork

In this (very contrived) example the logic is that the Rating column is editable but values must be between 10 and 20 (with 15 not allowed).
As a result 3 Server Validation Rules will be applied (and each will display a Message):
- value > 20 will return 20 - with a messageType of Warning and custom Message Header
- value < 10 will return 10 - no messageType set (so it defaults to Info)
- value of exactly 15 will be rejected - with a messageType of Error and custom Message Header
Any edits that don't break those rules - or which are not for the Rating column - we ignore (and they will be processed normally).

Expand to see the Server Validation Rule

The rule is provided in validateOnServer function in editOptions:

editOptions: {
  validateOnServer: (serverValidationContext: ServerValidationContext) => {
    return new Promise((resolve, reject) => {
      setTimeout( // mimic a server check
        () => resolve(getServerEditResponse(serverValidationContext.cellDataChangedInfo)),
        1000
      );
    });
  },
},

Using this logic:

function getServerEditResponse(
  cellDataChangedInfo: CellDataChangedInfo
): ServerValidationResult {
  if (cellDataChangedInfo.column.columnId == 'rating') {
    if (cellDataChangedInfo.newValue == 15) {
      return {
        newCellValue: cellDataChangedInfo.oldValue,
        validationMessage: 'Cannot provide Rating of 15',
        validationHeader: 'Not Allowed',
        messageType: 'Error',
      };
    } else if (cellDataChangedInfo.newValue > 20) {
      return {
        newCellValue: 20,
        validationMessage: 'Rating cannot be greater than 20',
        validationHeader: 'Too High',
        messageType: 'Warning',
      };
    } else if (cellDataChangedInfo.newValue < 10) {
      return {
        newCellValue: 10,
        validationMessage: 'Rating cannot be less than 10',
      };
    }
  }
  return {};
}

import {
  AdaptableOptions,
  CellDataChangedInfo,
  ServerValidationContext,
  ServerValidationResult,
} from '@adaptabletools/adaptable';
import {Car} from './rowData';

export const adaptableOptions: AdaptableOptions<Car> = {
  primaryKey: 'model',
  adaptableId: 'Server Validation',
  editOptions: {
    validateOnServer: (serverValidationContext: ServerValidationContext) => {
      return new Promise((resolve, reject) => {
        setTimeout(
          // mimic a server check
          () =>
            resolve(
              getServerEditResponse(serverValidationContext.cellDataChangedInfo)
            ),
          1000
        );
      });
    },
  },
  initialState: {
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'has_projects',
            'has_pages',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

function getServerEditResponse(
  cellDataChangedInfo: CellDataChangedInfo
): ServerValidationResult {
  if (cellDataChangedInfo.column.columnId == 'rating') {
    if (cellDataChangedInfo.newValue == 15) {
      return {
        newCellValue: cellDataChangedInfo.oldValue,
        validationMessage: 'Cannot provide Rating of 15',
        validationHeader: 'Not Allowed',
        messageType: 'Error',
      };
    } else if (cellDataChangedInfo.newValue > 20) {
      return {
        newCellValue: 20,
        validationMessage: 'Rating cannot be greater than 20',
        validationHeader: 'Too High',
        messageType: 'Warning',
      };
    } else if (cellDataChangedInfo.newValue < 10) {
      return {
        newCellValue: 10,
        validationMessage: 'Rating cannot be less than 10',
      };
    }
  }
  return {};
}

Server Validation

(Recorded with AdapTable v15.0)

PreviousClient Validation NextData Change History

Framework: