UI5ers Buzz #59: UI5 Custom Currency and Unit of Measure for OData V2 smart controls

[vvelinov]

Business applications often use different currencies or units of measure. Until recently, the possibility to work with currency and units of measure provided by SAPUI5 was somewhat limited. To fill in this gap, we provided a flexible turn-key solution for business applications.

UI5 already supported application developers to properly format, parse and store such data by providing formatting and parsing based on the Common Locale Data Repository (CLDR). With an ABAP backend, however, CLDR may not be sufficient. The units defined in the ABAP system do not match the unit keys in CLDR. Additional units or currencies may have been defined in the ABAP system or existing customizing may have been adapted. For OData V4 a solution has been available for two years now. The unit and currency customizing are loaded as code lists from the same ABAP system as the data. That solution brought about the types sap.ui.model.odata.type.Curreny and sap.ui.model.odata.type.Unit. Although the development was clearly motivated by ABAP backends, the UI5 functionality works with other backends as well.

As of SAPUI5 1.90, a similar solution has also been introduced for OData V2. We now support currency and unit of measure code lists in the model. The main difference to the OData V4 solution is that the code lists must be exposed as additional entity sets of the same service. The types sap.ui.model.odata.type.Currency and sap.ui.model.odata.type.Unit are used by the smart field and the formatting of the smart table uses the unit and currency code lists, if available, for formatting in display mode. The solution will fall back to the previous behavior if the respective code list is not available

The following example shows how the unit of measure code list in entity set SAP__UnitsOfMeasure is announced with the UnitsOfMeasure annotation.

<Annotation Term="com.sap.vocabularies.CodeList.v1.UnitsOfMeasure">

            <Record>

                        <PropertyValue Property="Url" String="./$metadata"/>

                        <PropertyValue Property="CollectionPath" String="SAP__UnitsOfMeasure"/>

            </Record>

</Annotation>

Then you need to define the corresponding entity type with its properties. Further annotations are used to describe the meaning of the properties of the entity type. See Currency and Unit Customizing in OData V2.

Handling custom currency and unit of measure in the smart field

The smart field uses composite types for currency and units. They have built-in functionality to handle code lists of currencies or units and provide the input validation and formatting out of the box. Once annotations defining currency or unit code list are loaded, a request would be sent to the backend to fetch the code list itself. This is done only once. When code list has been loaded validations are done based on it.

For example, if for currency “USD” the code list defines 3 decimal places and local CLDR list 2, smart field will make the validation based on the value in the code list. In that case, value such as ‘2.345’ will be valid and value entered as ‘2.1’ will be formatted as ‘2.100’.

Let's look at how currency validation works with few examples. If we have custom currency ‘EUR3’ in the code list, for which there are 3 decimals, then formatting is applied and we have 3 decimal places.

Currency EUR3 with three decimals

Now, if we change to a currency with 2 decimal places, while preserving the value, the validation will fail. For instance, switching to ‘EUR’ will lead to a validation error.

Switching from currency with three decimals to currency EUR with two decimals

This validation mechanism existed already working with locally defined currency in CLDR or locally added custom currencies. Now, it is enhanced so that validation is based on the custom list if such is provided by the backend.

Let's also see few examples for unit of measure. In contrast to the currency, up to now CLDR was not used by smart field, and all formatting was based on scale property of the field, or if such was not set, the default was 3 decimals. Now, with the usage of sap.ui.model.odata.type.Unit when we select a unit, the quantity is automatically formatted, just as for the currency. In this example, we have selected ‘KG’ with 3 decimal places. That’s why the entered quantity of ‘2’ is formatted as ‘2.000’.

Unit with three decimals

When we change the unit to ‘MGG’ with the number of decimals equal to ‘0’, the formatting automatically removes the trailing zeros and changes the quantity to ‘2’.

Switching from unit with three decimals to unit with no decimals

If we enter a decimal number, it will be invalid:

Unit doesn't allow decimals and smart field shows validation error

But if we change the unit to ‘KG’, the field will be marked as valid and will be formatted based on the definition of the unit.

Switching to another unit with three decimals

The invalid value message again depends on the definition of the unit in the  code list. If the scale property of the field is different than that of the type, the validation will take into account the lower of the two.

Trying to type more decimals than unit allows

Smart table

Smart table respects now the code list customization for currencies and unit of measures for the automatic created read-only column content. In older SAPUI5 releases the formatting of the currencies were only based on CLDR information. For unit of measures a default format was used.

This example demonstrates the behavior.

As before the values with amount and currency columns are aligned at the decimal point for better readability and comparability. This alignment is now also improved by using for the units the new monospaced 72 font.

Smart table alignment of currencies and units

Preserve decimals – showing the real data from the backend

Often it could be the case that the application developer is enhancing an existing application that already has data in the backend. In some cases, this could cause some decimals to be cut off. Especially with the way we’ve changed unit handling to take into account the corresponding unit formatting.

To address this, preserveDecimals formatting option was introduced in 1.87 and it is enabled by default as of 1.89, unless formatOption style is either short or long. This property is also valid for composite or  numeric types such as sap.ui.model.odata.type.Curreny and sap.ui.model.odata.type.Decimal  When preserveDecimals is true, extra decimal digits coming from the backend will not be truncated. Keep in mind that, if preserveDecimals is enabled for a field, that could cause misalignment when displayed in a table.

With SAPUI5 1.92 also also the preserveDecimals functionality is enabled by default in the Smart table.

Conclusion

To sum up, when it comes to currency and unit of measure our solution caters for all needs of your application - whether it be an ISO standard defined via CLDR, locally defined in the application, or provided by the backend in the form of code list. Smart controls, like smart field and smart table provide this functionality out of the box, no additional coding needed, just proper annotation and code list definition provided by the backend.

Further reading

If you’re interested, you can check out our documentation on currency and unit formatting.

To find out more about how unit and currency code lists are defined and work with OData V2 and OData V4, check out the chapters Currency and Unit Customizing in OData V2 and Currency and Unit Customizing in OData V4.

Previous post: UI5ers Buzz #58: Column resizing & Auto pop-in feature in Responsive table

Author

Mathias is Product Owner in SAPUI5 development and he and his team are focusing on the development of the OData V4 Model for SAPUI5 and OpenUI5. Before joining SAPUI5, Mathias worked in various roles for SAP Solution Manager development and the service development of former Active Global Support.

Jens is software developer and architect at SAP since 2006 in the area of web-based user interfaces. He joined the UI5 development team shortly after the project was started. Today he's the Product Owner of UI5 Tables.

Vladimir is a Product Owner in UI5 having 20 years of SAP experience in various roles. Current focus is on Smart Controls. Previously was PO for Date and Time controls in UI5. Has background in delivery infrastructure for SAP technologies. In free time often plays around with IoT projects, 3d printing or practice Qi Gong.