What’s in this blog post…

Data Types

Data types in SAPUI5 are used as a mechanism to validate user input (“hello” isn’t an acceptable value for order quantity, for example) and also to ensure      that data is formatted and displayed appropriately on the UI (like displaying 1234567 as 1,234,567 where required). When used in conjunction with a data model that supports 2-way binding – which is the best way to use them – data types ensure that the data in the model gets updated only if the user provides a valid value.

User input validation can also be done by writing validation logic in event handlers for every single input fields; and formatting displayed values can be done by writing and using formatters wherever values are displayed. As you can already guess though however, this does not scale well and the effort required to maintain a development done with this approach would quickly get high as the application grows.

The SAPUI5 framework comes with some commonly needed data types that can be used in applications. These include Boolean, Date and Float. The behaviour of bindings that use data types can be tweaked by specifying constraints and format options. Constraints (like minimum and maximum for Float) can be used to restrict the range of values that are considered valid. Any user input that violates a constraint is considered to be invalid input, and the corresponding path in the model will not be updated. Format options on the other hand, are specified to configure how a particular value should be displayed on the UI (like groupingSeparator and decimalSeparator for Float). The value at the corresponding path in the model is formatted according to the type’s format options before being displayed. Additionally, the user is also able to enter inputs either with (like 12,345) or without formatting (12345) – and both of these are considered valid.

Custom Data Types

For most requirements, using standard data types (sap.ui.model.type.*) with suitable constraints and format options will suffice. But there can be some requirements (like the example we’ll be working on later in this post) which cannot be satisfied with constraints on standard data types. In these cases, we will need to develop our own data types. We will now look at what all goes into creating a custom data type, along with an example – A custom data type for handling credit card numbers.

To get started with creating a custom data type, we extend the sap.ui.model.SimpleType class and override 3 methods defined in the SimpleType parent class – parseValue, validateValue and formatValue

parseValue(sExternalValue)

This method receives the user’s input as a parameter. This method’s job is to convert the user’s value (external value) into a suitable internal representation of the value (internal value). In our credit card number example, one possible implementation would be to convert the user’s input “4556-2364-5346-4444” into an internal representation without the hyphens “4556236453464444”. The use of doing this becomes obvious when we start implementing one of our other 2 methods – validateValue

validateValue(sInternalValue)

This method receives the parsed value (that is, the internal representation of the value as determined by the parseValue method) and must decide whether or not the value is valid. If the input is determined to be invalid, an exception of type sap.ui.model.ValidateException should be thrown from within this method.

formatValue(sInternalValue)

This method receives the parsed value (internal value) as a parameter and must return a formatted value (that is, a corresponding external value). This formatted value is displayed on the UI.

Before we start implementing our custom data type, let’s have a quick look at when exactly the framework calls each of these 3 methods. We see from the diagram, that the order in which these 3 methods are triggered by the framework is parseValue() -> validateValue() -> formatValue().

The ‘Credit card number’ custom data type

parseValue(sExternalValue)

For our example, we’ll just remove any hyphens that are present in the user input using a regular expression, and return the result as the parsed value (as a string of digits). To indicate to the framework that input could not be parsed (for example, trying to parse the string “hello” to a date), throw an exception of type sap.ui.model.ParseException – we don’t do this in our example though.

validateValue(sInternalValue)

For validating whether we’re dealing with a valid credit card number or not, we will implement the Luhn’s algorithm in our validateValue method. To tell the framework that validation failed, we raise a sap.ui.model.ValidateException near the end of the method.

formatValue(sInternalValue)

To format the internal value that we obtained via our parseValue method (which is a string of 16 digits), we add a hyphen after every 4 digits and return the new string from this method (so “1234123412341234” becomes “1234-1234-1234-1234”). This value is then set for the ‘value’ property of our input field, and is visible on the UI.

XML Binding

With our custom data type now ready, we go ahead and bind our input field to a path in our JSONModel (you can use it with other model types too though) and specify a type for the property binding.

Controller

Let’s wire in the MessageManager and ask it to do the magic of actually showing the error message to the user for us. This is documented in the UI5 Demokit (OpenUI5 SDK – Demo Kit)

The Result (click on the image if you don’t see it animated)

Do you have any feedback on this post? Or a discussion around it that you’d like to start? Go ahead and drop a comment. 🙂