-
Notifications
You must be signed in to change notification settings - Fork 162
Grid Validation Specification
- Overview
- User Stories
- Functionality
- Test Scenarios
- Accessibility
- Assumptions and Limitations
- References
Grinders
Developer Name
Designer Name
- Peer Developer Name | Date:
- Design Manager Name | Date:
- Product Owner Name | Date:
- Platform Architect Name | Date:
Version | Users | Date | Notes |
---|---|---|---|
1 | Maya Kirova | Date | Initial Draft |
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
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. ...
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.
Describe behavior, design, look and feel of the implemented feature. Always include visual mock-up
3.1. End-User Experience
** Integration scenarios or functionality with other features/components prototype ** End-to-end user experienceprototype ** Prepared design files for styling e.g. interplay with features and light/dark variants design hand-off
- 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
- 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
Name | Description | Type | Default value | Valid values |
---|---|---|---|---|
Name | Description | Return type | Parameters |
---|---|---|---|
Name | Description | Cancelable | Parameters |
---|---|---|---|
Automation
- Scenario 1:
- scenario 2:
ARIA Support
RTL Support
Assumptions | Limitation Notes |
---|---|
Specify all referenced external sources