Grid Validation Specification

Owned by

Grinders

Developer Name Maya Kirova

Designer Name

Requires approval from

Svilen Dimchevski | Date:
Konstantin Dinev | Date:
Stamen Stoychev | Date:
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 pending transactions and the related validation state. An additional API - getInvalidTransactionLog is exposed to return invalid 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,submit.

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' , 'submit'

Methods (igxBaseTransactionService)

Name	Description	Return type	Parameters
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