@elevatory/ui5-validator

UI5 Input Validator

UI5 Input Validator is designed to help you with validating UI5 input controls. You canvalidate a control or a whole control container with a single line of code.

Installation

npm install @elevatory/ui5-validator

In order to make UI5 Input Validator available for your application you have to bring Validator.js to your application folder. The easiest way is to copy the file from the node_modules folder to your source code folder. Please keep in mind, that you have to carry out the copy step again whenever you install a new version of the Validator via npm.

Another option is to use a bundler and a transpiler to create a serve & build step that automates the process of including npm modules into UI5 applications.

Luckily there is a great project UI5 Tooling Extensions for NPM Package Consumption that does all of that for you. Check it out.

Required i18n Texts

UI5 Input Validator uses i18n-Texts for to show error messages. These texts appear below a control that has an error state caused by a failed validation. The following texts must be included in your i18n files. Feel free to provide any text you prefer.

validatorMandatoryFieldEmpty=Please provide a value
validatorMandatorySelectEmpty=Please select an option
validatorCustomTypeInvalid=Please provide a valid value

The texts need to be stored in a ResourceModel named i18n.

Usage

As soon as you have UI5 Input Validator in you source folder, you can use it in any UI5 Code file. You will most likely use it in some of your controllers.

Import the Module

If you prefer JavaScript for your UI5 application, you just have to add the module to the imports of your object within sap.ui.define.

sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "../lib/Validator"
], function (Controller, Validator) {
	...
})

If you use TypeScript with a UI5 transpiler, you can import the file.

import Validator from "@elevatory/ui5-validator";

Create an Instance

You can create an instance of the validator by calling the constructor.

this.validator = new Validator(this.getOwnerComponent());

Please note that you have to provide a reference to the application component.

Run Validation

You can run an input validation by calling the method validate of the Validator instance. The methods takes a reference of an UI5 control or a control container as an input.

const validator = new Validator(this.getOwnerComponent());

if (validator.validate(this.byId("salesPriceForm"))) {
    this.getView().getModel().submitChanges();
    this.getView().byId("salesPriceDialog").close();
}

The validate method alters the ValueState of the given controls. If the validation fails, the ValueState will be set to Error otherwise it will be set to None.

In additon the method returns true or false reflecting the success of the validation.

You can also clear the ValueState via code by calling the clearValueState method.

const validator = new Validator(this.getOwnerComponent());
validator.clearValueState(this.byId('salesPriceForm'));

What gets validated?

• Type Restrictions: values in the input fields are checked against their type that is derived from model binding, including constraints
• Required: the control must have a value, if it has the property required="true"or contains a CSS class with the name customRequired
• Custom Validations: a custom validator method can be provided for complex checks (see Custom Validations)

HINT If a control does not have a required property, just use the CSS class customRequired to tag the control as required

Who gets validated?

You can provide any control to the validation method that contains one of the following properties:

• value
• selectedKey
• text
• dateValue
• secondValue
• selectedIndex

If you want to validate multiple controls at once, you can instead provide a control container. The Validator tries to recursivly find all child controls of the given container by checking its aggregations.

Custom Validations

In case you want to use complex validations, you can add a reference to a validator function via customData. You have use the key validation and the name of your controller function, that does the validation, as the value.

The following example adds a simple zip code validation to an input control. In your view:

<Input value="{zipCode}" required="true" maxLength="5" id="idZipCode">
    <customData>
        <core:CustomData key="validation" value="validateZipCode" />
    </customData>
</Input>

In your JavaScript controller:

validateZipCode: function(value) {
    if (value.length !== 5) {
        throw new Error("Please provide a valid zip code.");
    }
}

In your TypeScript controller:

public validateZipCode(value: string): void {
    if (value.length !== 5) {
        throw new Error("Please provide a valid zip code.");
    }
}

You can put any complex JavaScript logic inside the validation method. It is also possible to use async methods for validation. The value to be validated (see Who gets validated?) is passed to the validation method via a parameter.

The validation is seen as successfull if the method does not raise an exception. This means that you have to throw an exception if the validation fails.

Problems with Validation and Flickering of ValueStates

In case the validation flickers and only displays an error for a splitsecond, it might be due to activated handleValidation.
Set handleValidation to false in your manifest.json.

{
...
    "sap.ui5": {
        ...
        "handleValidation": false,
        ...
    }
}

Authors

The development is carried out by Elevatory. We specialize in the development of SAP applications with ABAP, SAPUI5/Fiori and SAP HANA.

The original idea and source is taken form this great project SAPUI5 demo - (Multiple) Form Validation