---

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

Common customization usage cases:

Changes from the default ISO country names/codes: For example, the nation name - USA - can be written in a variety of ways, including US, United States, America, United States of America, and so on. Deviations from ISO-a2 standard names/codes can be corrected by adding synonyms to the dictionary file. (For constructing synonyms, please see the dictionary property section.)

** A different world map projection is required, or the customer wants certain alternative shapes of maps, such as retail layouts or hotel layouts that show occupancy, and so on.**

To create custom maps, the user must understand the following terms. First, tell us about the files in the map chart folder. When you unzip the vitara map chart plugin, you will see the following folders: custom, data, javascript, style, and WEB-INF.

It is recommended that users use the “custom” folder to generate or save any files when creating custom charts. There are two crucial subfolders in the ‘custom’ folder: dictionaries and shapes. A text file called’mapping layers’ is also included in the ‘custom’ folder. All mapping layers are loaded into this root file form.

The path to the custom folder in your vitara map chart installation is shown below. 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/

‘Map layer’ refers to a map in a vitara map chart. In the vitara map chart, for example, there are three preset maps. A map layer must be defined for each of these maps. There are three definitions of map layers in the mapping layers text file: world physical, US Physical, and US Counties.

To add a new map layer, use the notation <ns>.property.

<ns>: NameSpace, which can be any alphabetic combination, but must be unique for each new map layer. The map layer should have the following attributes:

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

Name Property:

It’s the name we’d want to give our map. For example, if I want to make a map that shows the human population for each continent and name it ‘world continents,’ the name property definition would be as follows:

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:

This file is in geojson (.json) format.This file contains information on the borders of areas on a map. The needed shape file can be downloaded from online resources or produced using various applications. Download geojson shape-files from this link: http://code.highcharts.com/mapdata/

The shape file for our global continent example can be downloaded straight from the URL below. http://code.highcharts.com/mapdata/custom/world-continents.geo.json

A shape file with the name “world-continents.geo” (.geo.json extension) will be obtained by clicking on the preceding link. The downloaded file should be placed in the following directory. VitaraMaps\custom\shapes

The path where we copied our map’s shape file should be specified in the shape property specification.

The shape property definition for globe continents is as follows, as we copied the shape file into VitaraMapscustomshapes folder.

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

All shape files should be saved in the ‘Shapes’ folder of the custom folder. This is not required, however it is preferable in terms of naming convention.

‘Dictionary key’ Property:

The word ‘dictionary key’ refers to the unique name assigned to each map division. In the world’s continents example, there might be six partitions in the map representing each continent: Africa, Asia, Europe, North America, Oceania, and South America (excluding Antarctica, which has no human inhabitants). Each partition should now have a distinct name by which it may be identified. These distinct names are specified in the shape file.

Open the downloaded shapefile “world-continents.geo” in any text editor, such as notepad, for our world continents example. Make a copy of the whole contents of this file.

Use any online json reader, such as http://jsonviewer.stack.hu/, to open the shapefile in json structure.

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.

One of the objects in the json tree structure is the ‘features’ array. We have objects for each segment of the chart if we expand the ‘features’ array. In our world continents example, there are objects numbered 0 to 5 because there are six partitions in the chart representing each continent (except Antarctica)..

Now expand any object, for example ‘0’.

Expand ‘properties’ in ‘0’ object.

A few fields define a unique name for each partition of the map chart. We can use the name that fits our data as a ‘dictionary key’. For instance, I have the following data in which continents are represented by 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.

Take a look at the ‘Australia’ continent. Let’s compare this to the shapefile and look for unique names linked with each map segment.

Except for Australia, which is named “Oceania” in shape file, the names of the continents in our data and the unique names in shapefile by which each area of the globe is defined are the same. As a result, Map chart does not recognize the word ‘Australia’ in our data file. The map chart displays the partitions in the shapefile. However, because this partition does not match the name we are calling in our data file, it does not display any data in the map chart. Please see the marked region in the screenshot below.

Similarly, if the data differs from the unique names in the shapefile, or if the shapefile only contains ISO-a2 codes and our data has names for these codes, we have created a text that lists’ synonyms’ for the names in the shapefile and the names in the data. Let us make a synonym for our example: World continent. We must match the name in the shapefile - “Oceania” - with the name in the data, “Australia.” ‘Australia’ has replaced ‘Oceania’ as a synonym. All of the synonyms must be listed in a text file in this manner.

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:

The primary purpose of the grouping option is to make it easier to group individual regions on the map as a single unit, as opposed to regions with a single boundary. Vitara Map chart will draw any map for the regions given in the shapefile by default. For example, in the screenshot below, the Vitara Map chart displays a map of the world’s countries. We must utilize the world countries shapefile to create this map. As a result, by default, this map graphic will accept data at the country level.

To build this map at a higher level, for example, countries organizations such as NATO, BRICS, and so on, we must enable ‘Grouping’ in the Vitara Map chart. A screenshot of a sample data file with both country and organization columns is shown below.

To show the data in Vitara Map chart at which level, we must add that attribute to the “Map Attribute” drop zone. If we add the ‘Country’ attribute, the map will display data by country, and if we add the ‘Organization’ attribute, the chart will display data at this level.

Because we used a shapefile with nation information in the preceding example, the Vitara map chart will display country level data by default. However, if we wish to display the data at a higher level, we must use the ‘Grouping’ property.

To group separate regions, we must first construct a text file that lists all of the distinct regions. The following is the format for defining a group: Group name = List of individual areas in comma separated format.

Save this text file in the custom folder’s ‘dictionaries’ folder. The screenshot below is of a group text file that I made. In our example, I named the group file ‘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 outcome of grouping in the globe physical map is shown below. When we move the mouse over any of the grouping regions, all of the items in the group and all of the regions will appear in a single color.