SAPUI5 Developer Center: Custom Data

Types in SAPUI5
Posted by Pritin Tyagaraj Sep 16, 2016

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

Generated by Jive on 2016-10-06Z

1

SAPUI5 Developer Center: Custom Data Types in SAPUI5

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

Generated by Jive on 2016-10-06Z

2

SAPUI5 Developer Center: Custom Data Types in SAPUI5

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.

Generated by Jive on 2016-10-06Z

3

SAPUI5 Developer Center: Custom Data Types in SAPUI5

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

Generated by Jive on 2016-10-06Z

4

SAPUI5 Developer Center: Custom Data Types in SAPUI5

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

Generated by Jive on 2016-10-06Z

5

SAPUI5 Developer Center: Custom Data Types in SAPUI5

"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)

Generated by Jive on 2016-10-06Z

6

SAPUI5 Developer Center: Custom Data Types in SAPUI5

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

Generated by Jive on 2016-10-06Z

7

SAPUI5 Developer Center: Custom Data Types in SAPUI5

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.
744 Views Tags: html5, binding, frontend, sap_ui5, ui5, custom_data_type

Christopher Solomon
Sep 16, 2016 5:32 PM
Very nice! I like when someone goes into the finer details on a specific subject that is often "glossed over" in
the normal material. Thanks and keep blogging!
Sergio Guerrero
Sep 16, 2016 3:31 PM
thanks for sharing this blog Pritin, also, it adds a lot of value to add the Luhn's reference because I think some
people that have not dealt with these rules know the background of how CC gets validated, and also it depends
on the type of CC which values are considered correct or incorrect.
I also like the part where you included the MessageManager into your blog - nice addition there. Great share!

Generated by Jive on 2016-10-06Z

8