Background

In this blog post, I’ll introduce a reusable choropleth map UI5 control that can be bind to a model.

There are already a few examples (e.g. Konstantin Anikeev ‘s blog and John Patterson ‘s blog) of how to use maps with UI5. They are mostly using Google Maps library and provide functionality such as geolocation and markers. I wanted to have a try with leaflet that is “An open-source JavaScript Library for Mobile-Friendly Interactive Maps” and use it for displaying tabular data on a map. My goal was to provide an easy-to-use UI5 component that provides the basic functionality of mapping tabular data, nothing more, nothing less.

A choropleth map is used to show proportional values, such as population density, on a map using shaded or patterned areas. It provides a visual tool for understanding variability of a given variable within a region. Choropleth maps are preferred form of map display when dealing with data that conforms to clearly defined areas, such as countries.

Here’s an example of UI5 choropleth map control bind to a model:

Live example

Implementation

I decided to make a control that can be used for displaying country data on a world map. For that I needed some data. Getting geographic data can be sometimes difficult especially if it has to be open source. Luckily there are more and more places that work to get more data more easily available. Examples are Natural Earth which is built by collaborators and supported by NACIS (North American Cartographic Information Society), and Open Knowledge (http://data.okfn.org/ ). I use Open Knowledge’s world country boundary json and World Bank’s GNI (gross national income) per capita datasets in the example. I also use MapQuest’s tile service to display the background map.

For the UI5 part of the implementation, I am creating a custom control  that handles the leaflet library. User only has to plugin the model to the control and define which fields contain the data that should be displayed. Implementation of the control can be found in github (link in the end of the post):

There’s two js/json files used in the example: countries.js contains the geoJson (multi)polygons for the world’s countries and GNIpercapita contains data about individual countries GNI. countries.js is used only by the control and user just needs to include it in the html page. GNIPerCapita is provided by the user and requirement is that the data contains a list of objects that have ISO3 country key in some field (this can be mapped with idField property) and a value (mapped with valueField property) that can be converted to a number using defined format. Format is hard-coded at the moment but could also be given using a metadata property or even callback function.

Here’s an example of the map

Integrating with model changes using UI5 Table

Getting the map to show was the first part but now let’s integrate the map with UI5 model changes. With a choropleth map, natural approach is to use table to modify the data so let’s do that next.

Integrating with the table actually requires almost no changes to the map control itself. We only have to bind the table to the model the map also uses and just refresh the map once there are changes. Even refreshing could probably be automated but I leave that as an exercise to the reader. You can find the code for integrating with the table in the end of the article. Here I show the output:

And after modifying the value for Russia (RUS) in the table:

Part 2 is available:

UI5 Choropleth Map Control with Live Examples – Part 2

Code:

kjokinen/ui5choroplethmap · GitHub

Live example

Thanks for reading!