Cell Validation

The Cell Validation Function enables proposed cell edits to be disallowed if they break custom rules.

note

Cell Validation Rules take place on the client. AdapTable also offers Server Validation (in Edit Options), where an edit is checked on the server and either the same, a new or no value is returned.

Validation Rules

Cell Validation is based on a CellValidationRule which determines whether or not a cell edit is valid.

warning

Cell Validation works by creating an ag-Grid Value Setter for the column in question.

This will REPLACE an existing Value Setter for the Column if one was set in GridOptions.

Cell Valdation Predicate

The Cell Validation Rule uses a Predicate - the same boolean function as is used as in filters.

Each Predicate has a type (e.g. GreaterThan) and, optionally, inputs (e.g. 100)

tip

Developers can easily provide their own Custom Predicates to create bespoke validation rules.

Using a Query

In more advanced scenarios (e.g. if the rule should look not only at the cell being edited but also at other values in the row) the Cell Validation Rule can additionally use an Adaptable Expression.

warning

In the scenario the Cell Validation Rule will only be applied if both the Predicate and Query return true

Cell Validation Rule Scope

Like many objects in AdapTable, Cell Validation uses Scope to determine where a Rule should be applied.

The Scope can be one, some or all columns, or it can be all columns of a particular DataType (or DataTypes).

UI Elements

Cell Validation includes the following UI Elements:

  • Popup - Shows a list of existing Cell Validation Rules with Edit and Delete buttons, plus an Add button to start the Cell Validation Wizard which facilitates the creation and editing of Cell Validation Rules.

  • Column Menu - Create Cell Validation Rule Menu Item starts the Cell Validation wizard using that Column as the Scope.

Entitlements

Cell Validation Entitlement Rules:

  • Full: Everything is available to the User

  • Hidden: Everything is hidden from the User and no Cell Validations will be triggered

  • ReadOnly: User can see Cell Validations defined in Predefined Config but not edit or delete them, nor add others.

Predefined Config

In Cell Validation Predefined Config it is possible to define multiple Cell ValidationRules.

PropertyDescription
CellValidationsCustom Cell Validation Rules to prevent invalid edits

Each Cell Validation Rule object contains just Predicate and Scope properties:

PropertyDescription
PredicateWhat triggers a CellValidationRule.
ScopeOn which Column(s) the CellValidationRule can be applied

Additionally a Query can be used to define the Cell Validation Rule which is defined as follows:

PropertyDescription
ExpressionExpression which will be evaluated (using AdapTable parser)
NameName of the Query - how it will appear in Query dropdown

Example

// Create 4 Cell Validation Rules:
// 1. No Number columns can be negative (using DataType scope)
// 2. No Edits allowed for the Emmployee Column
// 3. Invoiced Cost column cannot be greater than 300
// 4. No Edits allowed for Order Cost column in rows where Status is cancelled
// Note: This last Cell Validation Rule additionally uses an Expression
export default {
CellValidation: {
CellValidations: [
{
Scope:{
DataTypes: ['Number'],
},
Predicate:{
PredicateId: 'Negative'
}
}
{
Scope: {
ColumnIds: ['Employee'],
},
Predicate: {
PredicateId: 'Any',
},
},
{
Scope: {
ColumnIds: ['InvoicedCost'],
},
Predicate: {
PredicateId: 'GreaterThan',
Inputs: [300],
},
},
{
Scope: {
ColumnIds: ['OrderCost'],
},
Predicate: {
PredicateId: 'Any',
},
Expression: '[status]="Cancelled" ',
},
],
},
} as PredefinedConfig;

API Methods

The Cell Validation API contains the following methods:

MethodDescription
addCellValidation(cellValidationRule)Adds a Cell Validation Rule to State
deleteCellValidation(cellValidationRule)Removes a Cell Validation Rule from State
getAllCellValidation()Retrieves Cell Validation Rules from State
getCellValidationPredicateDefs()Retrieves all Predicate Defs available for Cell Validation Function
getCellValidationPredicateDefsForScope(scope)Retrieves all Cell Validation Predicate Defs which match given Scope
getCellValidationState()Retrieves Cell Validation section from AdapTable State
showCellValidationPopup()Opens Cell Validation popup screen

FAQ

Why add validation on the client - surely it should take place on the server?

You are right, validation should ideally take place on the server and hopefully it does for our users.

The Cell Validation function is not designed to replace Server Validation which AdapTable also offers

Instead Cell Validation specifically deals with 3 common use cases:

  • to add an extra level of validation so that you can prevent or set warnings for edits which are usually permitted, but which in particular scenarios or use cases should be avoided or checked first (e.g. if things are particularly volatile and you want to limit how much a cell can change by).

  • to avoid unnecessary round trips to the server, particularly if this will have other knock-on consequences or effect other users that might see their screen flash first with the new value and then again with the old value

  • as a temporary measure before Server Validation has been added; like all AdapTable objects, Cell Validation rules will ome into effect immediately after that they are created - there is no down-time needed, nor any custom development required, and no systems need to be restarted.

I dont want to stop the edit when a rule is broken but I do want to know; is that possible?

In older versions of AdapTable, Cell Validation had an ActionMode property which could be set to 'Warn User' and would display a warning.

This is no longer necessary as the new Alerts provides this - and much more.

More Information