Adding a custom map in Stimulsoft Dashboards
When designing dashboards, you can add a custom map. This map will be displayed in the common list of maps and in the user category.
To use a custom map in the design you should:
Add a map file to resources of a report;
In the editor of the Regional map, select this type of the map or drag and drop the resource from the dictionary to the dashboard.
Information
If you an invalid map file to the report resources, this type of the map will be marked in the list with the icon as on the picture below.
Creating a map file
A map file has the *.map extension, with the JSON markup of geographic data. The map file must contain the following fields:
Name. This is the name of the map;
Width and Height. Sets the width and height of the map.
The Paths array. Contains data of geographic objects of the map.
Each geographic object in the Paths array must contain the following fields:
Key. This is the identifier of the geographic object. It may only contain English characters “a-z”. It cannot contain spaces, special characters, dashes, etc.
EnglishName. This is the name of the geographic object.
Data. This is a patch of a geographic object.
ISOCode. This is the ISO code of a geographic object.
Editing a custom map
You may edit each map that is added to report resources. To do this:
Call the map resource editing form;
Click the Edit button in the resource editing form.
After that, the map editor will be called. In this editor, you can enable or disable geographic objects, customize the titles of geographic objects, and assign an icon to the map.
Information
Titles of geographic objects will be obtained from the EnglishName fields in the *.map file. Each title has an area in which the title text is placed. This area can be moved using the cursor keys (left, right, top, bottom). To resize an area, hold down the Shift key and use the cursor keys (top, right, left, bottom) to increase or decrease the size of the area in the corresponding directions.
A panel displays a list of geographic objects of the map. If the checkbox is selected, then the geographic object will be displayed on the preview panel of the current editor. If the box is unchecked, then the geographic object will not be displayed.
Map preview. This panel displays only enabled geographic objects.
The commands are used to align a title of a geographic object vertically.
The commands are used to align a title of a geographic object horizontally.
The option is used to wrap the title text. If the Word Wrap option is enabled, the title will be wrapped to the next line. Otherwise the text wrapping will be cut off along the border of the title area.
The Hide Text option. It is used to hide the title of the selected geographic object.
The Icon option. It is used to load a map icon. This icon will appear as a thumbnail in the map selection window.
An example of adding a map
Consider the example of adding a Haiti map to the list of regional maps.
Step 1: You should find the source of the map, which you will integrate into the list of maps, for example, Haiti.svg.
Step 2: Open this file using the editor, in the example case, using VSCode.
Step 3: Create a text file named Haiti.txt and open it in VSCode;
Information
Since the map file is created in the JSON format, you should first check the rules how to format this.
Step 4: In the Haiti.txt file, add the Name, Width, Height fields with the values. In the current example, the options added are “Name”: “Haiti”, “Width”: 700, “Height”: 700.
Step 5: In the file Haiti.txt, add a Paths array and move on to creating geographic objects of the map. To create a geographic object, you should specify the Key, EnglishName, Data, and ISOCode fields with values. Values for these fields can be taken from the source file Haiti.svg.
Step 6: Create the Key field in Haiti.txt and copy the value from the source file there. In the current Haiti.svg source file, you need to copy the value from the title field.
Information
Keep in mind that the Key field cannot contain spaces, dashes, special characters, etc. Key field can contain only Latin letters. Therefore, if the source file contains invalid characters, then when copying the values, they must be deleted.
All values in the Key field must be unique. It is not allowed to use the same values in several geographic objects. Each geographic object must have its own value in the Key field.
Step 7: Create the EnglishName field in the file Haiti.txt and copy the value from the source file there. This is the name of the geographic objects that will be displayed. Unlike the Key field, the value of this field may contain various characters.
Step 8: Create the Data field in Haiti.txt and copy the value from the source file there. In the current Haiti.svg source file, you need to copy the value from the d field.
Step 9: Create the ISOCode field in Haiti.txt and copy the value from the source file there. In the current Haiti.svg source file, you need to copy the value from the id field.
Step 10: Add the required number of geographic objects of the map;
Step 11: After adding all the geographic objects, you need to save the changes in the Haiti.txt file;
Step 12: Change the file type of Haiti.txt to Haiti.map;
Step 13: Launch the report designer and drag the Haiti.map file into the data dictionary;
Step 14: Add the Regional map element to the dashboard panel;
Step 15: In the map editor, select the Custom category, choose Haiti and click OK;
Step 16: Set the values of geographic objects and set the parameters of the Regional map element;
Step 17: Close the Regional map editor.
Now using this map you can design dashboards.
The added maps can be customized. Do the following to customize them:
Step 1: Select the Haiti resource in the data dictionary and click the Edit button in the data dictionary;
Step 2: Click the Edit button in the edit resource dialog;
Step 3: The map editor will be called;
Step 4: Uncheck the geographic objects, if you want to disable displaying them when working in the current editor;
Step 5: Select a geographic object in the list and change the location of the title area using the cursor keys (left, right, top, and bottom);
Step 6: Hold down the Shift key and use the cursor keys (left, right, top, and bottom) to resize the header area;
Step 7: Using the horizontal and vertical alignment, set the location of the title in its area;
Step 8: Enable text wrapping, if it is necessary that the title wraps to the next line when the text reaches the right border of the title area.
Step 9: Select the Hide Text option, if you do not want to display the title text;
Step 10: Click on the icon for the Icon parameter, if it is necessary to load a custom icon for the current map;
Step 11: Click the OK button in the map editor;
Step 12: Click the OK button in the resource editor.
Changes will be applied to the map of this type.
