SAPUI5 supports various ways to format numbers, for example the currency formatting – with version 1.54 SAPUI5 will also support the formatting and parsing of units, for example “12 km/h” or “35°C”. These unit formats are by default taken from the CLDR (see links below), but you can also define custom units for your app.
Analogue to the formatting of currencies, the new unit formatting feature allows you to combine a number value with a localized unit string. The actual numbers can of course still be formatted in all kinds of styles, e.g. with different decimals or fraction digits.
How to Use the New Feature?
The Simple Way
Since the units and their formatting patterns are already included in the respective language json files, you can simply instantiate a new unit format instance via the NumberFormat.getUnitInstance() factory. The resulting instance supports formatting and parsing. While the FormatOptions are used to format the Number itself, the specific unit code is passed to the format/parse method.
A More Complex Example
Besides a simple formatting and parsing of units defined in the CLDR, you can also use the known format options for formatting numbers independent of the unit. The style of the number output format can be defined as either “short” or “long”.
Essentially, the new unit formatting can be combined together with the existing number formatting.
The unit’s displayname can also be retrieved based on the data from the CLDR:
Creating Custom Units
The unit NumberFormat instance also allows you to specify custom-units, which can be used for formatting, as well as parsing. All you have to do is add your custom units as an additional parameter in the NumberFormat.getUnitInstance() factory.
The custom units defined on the number format instance will be exclusive to this instance. No other instances are affected. In addition, once you define custom units for an instance, only those units will be formatted and parsed by those instances.
This is done to circumvent ambiguities and unit clashes with the CLDR units. So in the above example, only Zombies can be formatted, but no Gigawatt (CLDR key: power-gigawatt).
If you need both, CLDR units and custom units, you simply have to created two separate number format instances.
Creating a New Unit Type
Besides the NumberFormat instances, you now can also include the new Unit type in your app. Simply define it as the type for a property binding, and most of the formatting and parsing effort will be handled for you out of the box.
Let’s look at an example for the usage of the new Unit type.
Think about a set of electric meters. Typically they all measure the flow of energy in kilowatt hours (kWh). Yet some meters are more precise than others, some measure up to a few hundred wattseconds, others just cap it at full kilowatt hours. To simplify it for our example: the number of decimals might differ depending on the type of electric meter.
In the above example we define a new MeterType to combine not only a number value and a unit, but the already mentioned optional dynamic format options in one single typed PropertyBinding.
With the new bindable dynamic format options of Unit type, you can pass the relevant meter formatting information in a generalized way through the cell’s bindings.
The third argument of the base Unit type constructor is a list of dynamic format options. In our example, the binding context itself contains the information on how many-decimals should be used. Yet these dynamic format options can be bound to any value from any model.
Please see our test pages and unit-tests. The live example pages will give you an overview of the usage and implementation for all presented new features:
Stay tuned for more features coming in 1.54!
Previous Post: UI5ers Buzz #23
Thorsten & Jacky
|Thorsten Hochreuther is UI5 Core Developer at SAP, improving the framework and digging deeper into the future of frontend development. When not brewing up new stuff for UI5, he’s a passionate cook and painter.|
|Jacky is UX Designer at SAP, working with the UI5 devs to make the framework better every day. She’s looking for ways to improve User Experiences – no matter if it’s web design, creative furniture or a dashing event.|