Grid Validation Specification

Owned by

Grinders

Developer Name

Designer Name

Requires approval from

Peer Developer Name | Date:
Svilen Dimchevski | Date:

Signed off by

Product Owner 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

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 a option to prevent editing from continuing in case of invalid input.

End-to-end user experience prototype

Acceptance criteria

Must-have before we can consider the feature a sprint candidate

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 when there are errors.
when igxTransactionService is used, then I should be able to get all invalid values before commiting.

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

Batch editing (Transactions)

In case there are transactions enabled for the grid and invalid values have been entered and submitted as a transaction, then the related cell should be marked with a igx-grid__td--invalid class. Once the transactions are submitted further tracking of the state is not possible so the cell will no longer be marked, it's up to the developer on application level to decide whether to allow invalid transactions to be commited into the data or not. Transactions can be checked before commiting them.

When no batch editing is enabled (no transactions are tracked) cell will show errors and will be marked as invalid only while the cell/row is in edit mode. Once the value is submitted in the data, state cannot be tracked further. It's up to developer to decide whether to allow entering and submitting an invalid value. The related cellEdit, rowEdit events can be canceled to prevent invalid input from entering the data.

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.3. Globalization/Localization

Describe any special localization requirements such as the number of localizable strings, regional formats

3.4. Keyboard Navigation

Keys	Description

3.5. API

Options

Name	Description	Type	Default value	Valid values

Methods

Name	Description	Return type	Parameters

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