---

Customization of Map chart (Creating maps other than default maps)

Common use cases for customization

• Changes in iso country names/codes from defaults: For example the country name - USA can be used in various forms, like - US, United States, America, United States of America, etc. Deviations in iso-a2 standard names/codes can be adjusted by creating synonyms in dictionary file. (Please refer dictionary property section for creating synonyms)

• Required different world map projection or user want some other shapes of maps like store layout or a hotel layouts which show occupancy, etc.

To generate custom maps user has to know the following terms. First let us know the files in map chart folder. You can find the following folders once you unzip vitara map chart plugin: custom, data, javascript, style, WEB-INF.

To create custom charts it is recommended that users may use “custom” folder to create or save any files. In ‘custom’ folder there are two important subfolders - dictionaries and shapes. The ‘custom’ folder also contain a text file - ‘mapping layers’. This is root file form which all mapping layers are loaded.

Below is the path of the custom folder in your vitara map chart installation. tomcat/webapps/MicroStratagy/plugins/VitaraMaps/custom/

The following section will explain the use of ‘dictionaries’ folder, ‘shapes’ folder, and ‘mapping layers’ text file.

Mapping layers text file:

The following is the screenshot of mapping layers text file which will be in the following path tomcat/webapps/MicroStratagy/plugins/VitaraMaps/custom/

The term ‘Map layer’ means a map in vitara map chart. For example, there are three default maps in vitara map chart. For each of these maps we have to define a map layer. In mapping layers text file you can see there are three definitions of map layers; world physical, US Physical and US Counties.

The following is the notation to add new map layer: <ns>.<property>

<ns>: NameSpace, this can be any combination of alphabets, but choose a unique value for each new map layer. The map layer should contain the following properties;

• <ns>.name =
• <ns>.shape =
• <ns>.dictionarykey =
• <ns>. dictionary =
• <ns>.groups = The ‘groups’ definition is optional.

Name Property:

It is the name we want to give to our map. For example, if i want to create a map which shows human population for each continent, and i want to give ‘world continents’ as the name of the map, then the name property definition would be as below:

kk.name = World Continents

Now, by using this name we can create a map which shows world continents. You can see this name in edit popup window → Map → Map Layer.

Shape property:

The format of this file is geojson (.json).This file contains data about boundaries of regions in a map. The shape file for our required map can be downloaded from online resources or can be created using various tools. Reference link to download geojson shape-files: http://code.highcharts.com/mapdata/

The shape file for our example of creating world continent can be downloaded directly from the following link. http://code.highcharts.com/mapdata/custom/world-continents.geo.json

By clicking on the above link a shape file with name “world-continents.geo” (.geo.json extension) will be downloaded. The downloaded file should be copied in to the following folder. VitaraMaps\custom\shapes

In the shape property definition we should give the path where we copied the shape file of our map.

For world continents example, as we copied the shape file into VitaraMaps\custom\shapes folder, the following is the shape property definition.

kk.shape = custom/shapes/world-continents.geo.json

All the shape files should be placed in ‘Shapes’ folder in custom folder. This is not compulsory, but in the naming convention point of view it’s better to do.

‘Dictionary key’ Property:

The term ‘dictionary key’ refers the unique name given to each partition of the map. In our world continents example there may be six partitions in the map representing each continent - Africa, Asia, Europe, North America, Oceania, South America (excluding Antarctica, as no humans lives in this continent). Now each of this partition should have a unique name by which it will be identified. These unique names are defined in shape file.

For our world continents example, open the downloaded shapefile - “world-continents.geo” using any text editor, for example - notepad. Copy the entire content of this file.

To open the shapefile in json structure use any online json viewers, for example: http://jsonviewer.stack.hu/

Now in the notepad copy the entire content of shapefile (.geo.json) and paste it in the “Text” tab of json viewer webpage. Now click on “Viewer” tab in json viewer webpage.

Now the geojson content will be displayed in json tree structure.

In json tree structure, one of the object is ‘features’ array. If we expand ‘features’ array we have objects for each partition of the chart. In our world continents example, as there are six partitions in the chart representing each continent (excluding antarctica), so there are objects named from 0 to 5.

Now expand any object, for example ‘0’.

Expand ‘properties’ in ‘0’ object.

There are few field which define a unique name for each partition of map chart. The name which matches with our data we can select it as a ‘dictionary key’. For example, i have the following data in which continents are represented in the form of names.

For this use case i have to use ‘name’ as dictionary key. Please refer the below screenshot.

For our world continents example, the following will be the dictionary key definition. Kk.dictionarykey = name

‘Dictionary’ property:

To know about this property lets take a look at our world continents map data excel file.

Look at the continent with name ‘Australia’. Now let’s compare this with the shapefile and check the unique names associated with each partition of the map.

The continents name we have in our data and the unique names in shapefile by which each part of the map was characterized are same, except Australia which is named as ‘Oceania” in shape file. For this reason Map chart does not know the name ‘Australia’ in our data file. Map chart shows the partitions which are in shapefile. But as this partition is not matching with the name we are calling in our data file, therefore this partition does not show any data in map chart. Please see circled area in below screenshot.

Similarly if the data differs with the unique names in shapefile or the shapefile has only iso-a2 codes and our data has names of these codes, we have create a text where we list ‘synonym’ for the names in shapefile with the names in data. Let’s create synonym for our example- World continents. We have to map the name in shapefile - ‘Oceania” with the name in data i.e. ‘Australia’. Now the synonym for ‘Oceania’ is ‘Australia’. Like this, all the synonyms we have to list in a text file.

I created a text file with name ‘worldcontinents’ and entered the synonym ‘Oceania = Australia’, and saved this file in VitaraMaps → custom → dictionaries folder.

We can list multiple synonyms also. Multiple synonyms should be comma separated.

For example, US = United States, United States of America, America, USA

Now the dictionary property definition in mapping layer text file tells about the path of the synonyms text file where we saved it.

For our example the property definition is: Kk.dictionary = custom/dictionaries/worldcontinents.txt

All such dictionaries files should be saved in ‘dictionaries’ folder in custom folder. This is not compulsory, but in the naming convention point of view it’s better to do.

As we added the synonym for ‘Oceania’ the map chart now shows the synonym i.e. ‘Australia’. Please refer the circled area in the below screenshot.

Till now, we had created all the property definitions for our example, world continents map, in mapping layers text file.

kk.name = World Continents

kk.shape = custom/shapes/world-continents.geo.json

kk.dictionarykey = ios-a2

kk.dictionary = custom/dictionaries/worldcontinents.txt

Save the mapping layers text file. Below is the screenshot of ‘mappingLayers’ text file after adding ‘worldcontinents’ map layer.

After saving mapping layers file, refresh your web browser. Once the map chart renders, go to Edit → Map → Expand - Map Layers, and apply the map which you created.

The below screenshot is the output of map chart, showing population in each continent.

Likewise other world map projections can be downloaded from the links provided below.

Reference link to download geojson shapefiles: http://code.highcharts.com/mapdata/

Reference link to convert existing ESRI maps to geojson file https://mygeodata.cloud/converter/shp-to-geojson

Others:

http://www.naturalearthdata.com/

http://geojson.io/

http://www.qgis.org/en/site/forusers/download.html

‘Groups’ Property:

Primary use for grouping option is to provide ease for grouping individual regions on the map as a single unit, as compared to region with single boundary. By default VitaraMap chart will draw any map for the regions defined in shapefile. For example, in the below screenshot VitaraMap chart is showing world countries map. To draw this map we have to use world countries shapefile. Therefor by default this map chart will accept the data at Country level.

If we want to draw this map at any higher level, for example, countries organizations like, NATO, BRICS, etc., we have to enable ‘Grouping’ in VitaraMap chart. Below is the screenshot of sample data file which has both country and organization columns.

At which level we want to show the data in Vitara Map chart we have to add that attribute to “Map Attribute” drop zone of Vitara Map chart. IF we add ‘Country’ attribute then map will show country wise data, and if add ‘Organization’ attribute then chart will show data at this level.

In the above example, as we used shapefile that has countries information, by default we Vitaramap chart will show country level data. But if we want to show the data at any higher level we have to use ‘Grouping’ property.

To group individual regions, we have to create a text file in which we have to list all the individual regions. The format of defining a group is, Group name = List of individuals regions in comma separated format.

Save this text file in ‘dictionaries’ folder in custom folder. The following is the screenshot of group text file which i created. In our example i saved the group file with the name ‘NATOBRICSgroups.txt’.

The next step is defining ‘groups’ property in ‘MappingLayers’ file. In groups property we have give the path of groups text file where we saved it. wp.groups = custom/dictionaries/NATOBRICSgroups.txt

The following is the screenshot of ‘MappingLayers’ file after adding groups property.

The last step to apply groups in vitara map chart is, enable Grouping” option under Map menu in property editor. (Edit → MAP → Enable Grouping). Screenshot is provided below for reference.

The below is the result of grouping in world physical map. When we hover cursor on any of the grouping regions all the elements in the group all the regions will show in a single color.