Configure VectorMap

This manual provides detailed instructions on how to configure the dxVectorMap widget. Having performed the actions refered in this topic, you will learn how to provide data for map areas and markers, choose the appropriate position of the map, customize map elements and interact with the map. These features will be explained on a simple example. As a result, you will get the dxVectorMap widget that displays the map of the United States with the capitals of 10 most populous states indicated on it.

Create a Vector Map

Start by creating an HTML file. Reference the required libraries in this file (see Add Libraries).

HTML
<!DOCTYPE html>
  <html>
      <head>
          <meta charset="utf-8" />
          <script type="text/javascript" src="jquery-2.0.3.min.js"></script>
          <!--script type="text/javascript" src="knockout-3.0.0.js"></script-->
          <!--script type="text/javascript" src="angular.min.js"></script-->
          <script type="text/javascript" src="globalize.min.js"></script>
          <script type="text/javascript" src="dx.chartjs.js"></script>
      </head>
      <body></body>
  </html>

There are several approaches to creating a ChartJS widget. This guide will utilize the jQuery approach. If you are interested in other approaches, refer to the Add a Widget tutorial.

Add a div element to the body of your HTML file. This element will contain the dxVectorMap widget.

HTML
<div id="mapContainer" style="height:450px; max-width:750px; margin:0px auto"></div>

Create dxVectorMap within this div container.

JavaScript
$(function () {
    $('#mapContainer').dxVectorMap({

    });
});

If you run this code, you will see an empty space with the control bar on the left side. In the next section, we will fill this space with a real map.

Provide Data

As we work to implement a US map with the capitals of the ten most populous states indicated on it, we must ensure to also provide data for the map. On our map, the states will be represented by areas, while the capitals will be indicated by markers. The next two subtopics explain how to provide data for areas and markers.

Data for Areas

Data for map areas can be provided using different approaches. All of them are described in the Data for Areas topic. The simplest approach uses the scripts supplied with the ChartJS library. To use one of these scripts on your map, reference it in the head of your HTML document.

HTML
<!DOCTYPE html>
  <html>
      <head>
          <meta charset="utf-8" />
          <!-- previously referenced libraries go here -->
          <script type="text/javascript" src="js/vectormap-data/usa.js"></script>
      </head>
      <body></body>
  </html>

After that, set the mapData option to the array defined in the referenced file.

JavaScript
$(function () {
    $('#mapContainer').dxVectorMap({
        // ...
        mapData: DevExpress.viz.map.sources.usa
        // ...
    });
});

Due to restrictions of the ChartJS website, data for areas is provided using a JSON object in this tutorial.

JavaScript
$(function () {
    $('#mapContainer').dxVectorMap({
        // ...
        mapData: '/Content/data/vectorMap-sources/usa.txt'
        // ...
    });
});

Data for Markers

Data for markers is provided using an array of objects, each of which should contain the 'coordinates' field. This field must be an array of two values: the first is the longitude, and the second is the latitude of a map marker. In addition, you can assign an object to the 'attributes' field. This object can contain any field you may find useful. This example will specify the name of the capital using the 'name' attribute.

Assign the array of markers to the markers field.

JavaScript
var markers = [{
    coordinates: [-121.2808, 38.3320],
    attributes: { name: 'Sacramento' }
}, {
    coordinates: [-97.75, 30.25],
    attributes: { name: 'Austin' }
}, {
    coordinates: [-73.7572, 42.6525],
    attributes: { name: 'Albany' }
},
// ...
];

$(function () {
    $('#mapContainer').dxVectorMap({
        // ...
        markers: markers
        // ...
    });
});

If you run this code now, you will see a map with the capitals indicated.

The next step will demonstrate how to position your map so that it fits perfectly within the widget borders.

Specify the Map Position

To configure your map, you will need to utilize positioning adjustments, e.g., zooming or centering on some point of the map. These actions can be performed using the bounds, center and zoomFactor options.

This example uses the bounds option to focus the map on the United States. To zoom the map, use the zoomFactor option, so that the marker labels, which will be added later in this tutorial, are displayed nicely.

JavaScript
$(function () {
    $('#mapContainer').dxVectorMap({
        // ...
        bounds: {
            minLon: -135,
            maxLon: -65,
            minLat: 20,
            maxLat: 60
        },
        zoomFactor: 1.25
        // ...
    });
});

The next step is to customize the appearance of the map areas and markers.

Customize the Appearance

This section tells how to customize the appearance of a vector map. Here, you will learn to change the background of your map and adjust several appearance options of map areas and markers.

First, paint the map background. For this purpose, we will use the color option of the background configuration object.

JavaScript
$(function () {
    $('#mapContainer').dxVectorMap({
        // ...
        background: {
            color: 'paleturquoise'
        }
        // ...
    });
});

Now, adjust the appearance of the main map elements - areas and markers.

Customize Areas

Areas and markers are configured using the same technique. Map areas are specified using the options of the areaSettings object, while markers are specified using the markerSettings object. Options that are specified on the first level of those objects are applied to all the areas or markers. However, there are several options that can be specified for each area or marker individually.

To specify options for a particular area, assign a callback function to the customize option of the areaSettings configuration object. You can find the list of the options that can be accessed with the customize function in the description of the corresponding option.

To implement our task, specify a special color for the areas that represent the top ten most populous states, while the other areas will be colored differently. To distinguish those special areas in code, declare and initialize an array that contains the names of the most populous states. Then, use the customize option of the areaSettings object to color the special areas. Note that to tell whether an area should be colored as special or not, the jQuery inArray function is used. The remaining areas are colored using the color option of the areaSettings object.

JavaScript
var mostPopulatedStates = ['California', 'Texas', 'New York', ...];

$(function () {
    $('#mapContainer').dxVectorMap({
        // ...
        areaSettings: {
            customize: function (area) {
                if (jQuery.inArray(area.attributes.name, mostPopulatedStates) != -1) {
                    return {
                        color: 'forestgreen'
                    }
                }
            },
            color: 'yellowgreen'
        }
        // ...
    });
});

In addition, specify a color for an area and its border when this area is selected using the selectedColor and selectedBorderColor options of the areaSettings configuration object.

JavaScript
$(function () {
    $('#mapContainer').dxVectorMap({
        // ...
        areaSettings: {
            // ...
            selectedColor: 'mediumaquamarine',
            selectedBorderColor: 'darkgreen'
        }
        // ...
    });
});

Customize Markers

To configure markers, use the options of the markerSettings configuration object.

To help identify markers on a map, they must be accompanied by a label. Assign a function returning an object that contains the text field to the customize option. Then, change the font size for the labels using the size option of the font configuration object. In addition, change the color of the marker when it is selected using the selectedColor option.

JavaScript
$(function () {
    $('#mapContainer').dxVectorMap({
        // ...
        markerSettings: {
            customize: function (m) {
                return {
                    text: m.attributes.name
                }
            },
            font: {
                size: 11
            },
            selectedColor: 'dodgerblue'  
        }
        // ...
    });
});

Add Interactive Features

This section will guide you through adding interactive features to map areas and markers. Use the areaSettings object to configure the areas. Specify a function that will select/deselect an area by a click, and assign it to the click option of the areaSettings object. In addition, allow users to select several areas using the selectionMode option.

To configure the markers, use the markerSettings configuration object. Add the capability to select a marker by a click, as we did for areas.

JavaScript
$(function () {
    $('#mapContainer').dxVectorMap({
        // ...
        areaSettings: {
            // ...
            click: function (area) {
                area.selected(!area.selected());
            },
            selectionMode: 'multiple'
        },
        markerSettings: {
            // ...
            click: function (marker) {
                marker.selected(!marker.selected());
            }
        }
        // ...
    });
});

Run this code now and you will see that your map has drastically changed its look. With the most complicated steps now completed, the next step involves configuring the control bar.

Configure the Control Bar

The control bar is a panel that helps you navigate your map at runtime. This panel contains the pan control and the zoom bar for panning and zooming the map correspondingly.

For our task, we will change the color of the control bar outline using the borderColor option of the controlBar configuration object.

JavaScript
$(function () {
    $('#mapContainer').dxVectorMap({
        // ...
        controlBar: {
            borderColor: 'lightseagreen'
        }
        // ...
    });
});

All that's left is enabling the tooltips. Move to the final step to do this.

Enable Tooltips

A tooltip is a small pop-up rectangle that displays information about an area or a marker when it is hovered over. By default, the tooltip is disabled, so we enable it with the enabled option of the tooltip object.

According to our task, a tooltip should display the name of the state that is currently hovered over. It can be performed using a function assigned to the customizeText option. This function will check the type of the element, which is currently hovered over, and if it is 'area', will return its name obtained from the 'name' attribute. This name will be displayed by the tooltip.

JavaScript
$(function () {
    $('#mapContainer').dxVectorMap({
        // ...
        tooltip: {
            enabled: true,
            customizeText: function (element) {
                if (element.type == 'area') {
                    return element.attribute('name');
                }
            }
        }
        // ...
    });
});

This tutorial guided you through configuring the dxVectorMap widget. You can find the full list of its options in the Reference section. The full code along with the resulting map can be found here.