Grid Validation Specification

Owned by

Grinders

Developer Name Maya Kirova

Designer Name

Requires approval from

Svilen Dimchevski | Date: 10 August, 2022
Konstantin Dinev | Date:
Stamen Stoychev | Date: 09 August, 2022
Deyan Kamburov | Date: 09 August, 2022

Signed off by

Radoslav Mirchev Name | Date:
Platform Architect Name | Date:

Revision History

Version	Users	Date	Notes
1	Maya Kirova	11/07/2022	Initial Draft
2	Svilen Dimchevski	21/07/2022	Updated Functionality section
3	Maya Kirova	03/08/2022	Update and polish specification

1. Overview

Objectives

igxGrid should allow validating user input when editing cells/rows.

Should extend Angular's reactive forms validation functionality to allow easier extensibility and maintainability.

Should show visual indicators (like error message, error styles etc.) when a cell/row enters invalid state.

Should have an option to prevent editing from continuing in case of invalid input.

End-to-end user experience prototype

Acceptance criteria

Should allow defining declaratively the default angular supported validators on the igx-column components. For example:

<igx-column required ...>

These should then be used for cell validation.

Should expose the generated FormGroup for the edited row/cell so that it can be customized by the user.
Should allow customizing the error's.

2. User Stories

Developer stories:

As a developer, I want to be able to:

declaratively set Angular's forms validators on the columns of the grid, so that I can validate the related cells on edit.
set my own custom validator, so that I can validate according to my business requirements.
customize the error messages.
access to the FormGroup used for validation so that I can further customize it.
prevent users from leaving edit mode for a cell/row when there are errors.
get all invalid values before commit.
set the validation trigger that would start validation on my inputs - similar to updateOn.

End-user stories:

Story 1: As an end-user, I want to get a descriptive validation message when I enter an invalid value, so that I can fix it.

3. Functionality

3.1. Design handoff- https://www.figma.com/file/fmatez7lHAxkXHhybPIhIa/Validation-message?node-id=0%3A1

Integration Scenarios

Base Transaction service

Base transaction service is modified to store validation transactions and the related validation state. Some additional APIs are also exposed:

getInvalidTransactionLog - Returns invalid transactions.
addValidation - Adds provided transaction with validation status.
getAggregatedValidationState- Returns the validation state of the record with provided id.
getAggregatedValidationChanges- Returns aggregated validation changes from all transactions

In case invalid value has been entered in the editor or submitted as a transaction, then the related cell is marked with a igx-grid__td--invalid class. Additionally an error icon with tooltip with the additional error message is displayed in the cell.

Transactions are created and receive a valid/invalid state once editing of the cell/row is complete. Transactions store that state until they are commited or cleared using the transaction service's methods - commit, clear.

Until then the invalid transactions will mark the related cells as invalid and display the style and error message(s).

Once the transactions are commited or cleared further tracking of the state is not possible so the cell will no longer be marked as invalid.

It is up to the developer on application level to decide whether to allow invalid transactions to be created at all and if so how to handle them on commit.

If no invalid values should be allowed to be entered in the data/transactions then the developer can cancel the cellEdit, rowEdit events to prevent entering an invalid state.
In case the developer would like to handle the invalid transactions himself he can do so via the getInvalidTransactionLog API from the grid.transactions object. He can collect the invalid values and decide how to proceed - whether to clear them, propt the user to fix them, allow commiting them etc., depending on the use case.

3.2. Developer Experience

3.2.1 Configuration

Validating via template-driven configuration

You can use the predefined angular forms validators declaratively on the igx-columns to enable validation for the related cells while editing:

<igx-column required minlength="4" ...>

These will then be injected for the cell when edit and used for validation.

The following will be supported out of the box, as we will extend the base angular directives to work on the igx-column:

required
min
max
email
minlength
maxlength
pattern

You can also defined your own custom directive that extends the column validator directive, for example:

  @Directive({
    selector: '[appForbiddenName]',
    providers: [{provide: NG_VALIDATORS, useExisting: ForbiddenValidatorDirective, multi: true}]
  })
  export class ForbiddenValidatorDirective extends IgxColumnValidator {
    @Input('appForbiddenName') 
    public forbiddenName = '';
  
    validate(control: AbstractControl): ValidationErrors | null {
      return this.forbiddenName ? forbiddenNameValidator(new RegExp(this.forbiddenName, 'i'))(control)
                                : null;
    }
  }

And use this in the column template:

<igx-column appForbiddenName='bob' ...>

Validating in reactive forms

We also expose the FormGroup that will be used for validation when editing starts on a row/cell via a onFormGroupCreate event. You can add validators to it for the related fields:

<igx-grid (onFormGroupCreate)='formCreateHandler($event)' ...>

public formCreateHandler(formGr: FormGroup) {
  // add a validator
  const prodName = formGr.get('UserName');
  prodName.addValidators(forbiddenNameValidator(/bob/i))
}

3.2.2 Customizing errors

The editing template can be modified with a custom one per column, for example:

<igx-column ... >
  <ng-template igxCellValidationError let-cell='cell'>
    <div *ngIf="cell.formGroup?.get(cell.column?.field).errors?.['forbiddenName']">
      This name is forbidden.
    </div>
  </ng-template>
</igx-column>

3.2.3 Prevent edit end when input is invalid

The editCell/editRow events can be canceled in case the isValid argument is false.

<igx-grid (cellEdit)='cellEdit($event)' ...>

public cellEdit(evt) {
  if (!evt.isValid) {
    evt.cancel = true;
  }
}

In that case the cell will remain in edit mode until a valid value is set.

3.2.3 Customizing the validation trigger.

The validation trigger can be set via the validationTrigger property:

<igx-grid #grid validationTrigger='blur'></igx-grid>

Valid values are change, blur.

3.3. Globalization/Localization

Default errors originating from the predefined angular forms validators that are set on the columns will have a default error message (i.e. required - This field is required.)

Default error message strings will need to be localized.

3.4. Keyboard Navigation

Keys	Description

3.5. API

Options

Name	Description	Type	Default value	Valid values
validationTrigger	Gets/Sets the trigger for validators used when editing the grid.	GridValidationTrigger	`change`	'change' , 'blur'

Methods (igxBaseTransactionService)

Name	Description	Return type	Parameters
addValidation	Adds provided transaction with validation status.	void	transaction: T, recordRef: any
getAggregatedValidationState	Returns the validation state of the record with provided id	T	id:Aany
getAggregatedValidationChanges	Returns aggregated validation changes from all transactions	T[]
getInvalidTransactionLog	Returns invalid transactions.	Array	id?:any

Events

Name	Description	Cancelable	Parameters
onFormGroupCreate	Event emitted when validation form group is created for an edited row. Emits the form group that with the form controls that will be used for validation.	false	FormGroup
onValidationStatusChange	Event emitted when validation status changes from valid to invalid or vice versa	false	IValidationStatus

4. Test Scenarios

Automation

Basic

should allow setting built-in validators via template-driven configuration on the <igx-column>.
should allow setting custom validator via template-driven configuration on the <igx-column>.
should allow setting validators on the exposed FormGroup object.
should allow setting validation triggers - 'change' , 'blur'.
should mark invalid cell with igx-grid__td--invalid class and show the related error cell template.
should show the error message on error icon hover and when the invalid cell becomes active.
should allow customizing the error message template.
should allow preventing edit mode for cell/row to end by canceling the related event if isValid event argument is false.
should trigger the onValidationStatusChange event on grid when validation status changes.
should return invalid transaction using the transaction's getInvalidTransactionLog method.