Providing Data

This topic goes over different approaches to providing data for the dxVectorMap widget. In case of this widget, providing data presumes specifying data sources for map areas and markers.

Data for Areas

To provide data for areas, follow one of these approaches.

Using a Script

The ChartJS Library is shipped with a number of predefined data sources for the dxVectorMap widget. You can find these sources as .js-scripts in the Lib/js/vectormap-data folder of the ChartJS zip-archive. Each data source contains an array describing a geographical territory. The following territories are available.

  • World (world.js)
  • Africa (africa.js)
  • Canada (canada.js)
  • Eurasia (eurasia.js)
  • Europe (europe.js)
  • USA (usa.js)

NOTE: Built-in maps were not created by DevExpress. They were taken from a free map data provider and converted to the dxVectorMap format with the parse() method. Refer to the Using a Binary Source section to learn how to display a custom map with the dxVectorMap widget.

To use one of these sources on your map, reference the corresponding file in the head of your HTML document. Note that this file should be referenced after the ChartJS Library file (see Add Libraries).

HTML
<!DOCTYPE html>
  <html>
      <head>
          <meta charset="utf-8" />
          <!-- libraries required by ChartJS go here -->
          <script type="text/javascript" src="js/dx.chartjs.js"></script>
          <script type="text/javascript" src="js/vectormap-data/world.js"></script>
      </head>
  </html>

Alternatively, the same data sources can be accessed and referenced using the DevExpress CDN.

HTML
<script type="text/javascript" src="http://cdn3.devexpress.com/jslib/13.2.13/js/vectormap-data/world.js"></script>
<script type="text/javascript" src="http://cdn3.devexpress.com/jslib/13.2.13/js/vectormap-data/africa.js"></script>
<script type="text/javascript" src="http://cdn3.devexpress.com/jslib/13.2.13/js/vectormap-data/canada.js"></script>
<script type="text/javascript" src="http://cdn3.devexpress.com/jslib/13.2.13/js/vectormap-data/eurasia.js"></script>
<script type="text/javascript" src="http://cdn3.devexpress.com/jslib/13.2.13/js/vectormap-data/europe.js"></script>
<script type="text/javascript" src="http://cdn3.devexpress.com/jslib/13.2.13/js/vectormap-data/usa.js"></script>

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

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

Using a JSON object

If you have your data as a JSON object, assign its URI to the mapData option. This way, no other actions will be required.

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

The JSON object used as a data source can be in the GeoJSON format. In such a case, this object should be a feature collection. Note that only the Polygon and MultiPolygon geometries are supported by the dxVectorMap widget. Properties of a GeoJSON object can be accessed using the area's attributes(name) method.

Using a Binary Source

The dxVectorMap widget can also receive data for areas from a binary source. Usually, this source comes as a shapefile. Files of this format describe vector features that represent various geographical objects. dxVectorMap can receive shape coordinates from a .shp file and attributes from a .dbf file.

There are two approaches to using a binary source as a data source for dxVectorMap.

Web Approach

NOTE: To use this approach, your web browser must support the DataView interface.

Reference an additional script in the head of your HTML document as follows. This script can be found in the Lib/js/vectormap-utils folder of the ChartJS zip-archive.

HTML
<!DOCTYPE html>
  <html>
      <head>
          <meta charset="utf-8" />
          <!-- libraries required by ChartJS go here -->
          <script type="text/javascript" src="js/dx.chartjs.js"></script>
          <script type="text/javascript" src="js/vectormap-utils/dx.vectormaputils.js"></script>
      </head>
  </html>

The referenced script contains the parse() method for parsing a binary source into the format supported by the dxVectorMap widget. There are two possible ways of using this method.

  • Using a Shapefile
    If you can access a required shapefile via XMLHttpRequest(), use the following construction.

    JavaScript
    DevExpress.viz.vectormaputils.parse('/shapeSources/world', { precision: 2 }, function (data) {
        $('#mapContainer').dxVectorMap({
            mapData: data.features
        });
    });

    In this code, the function's first argument specifies the URI of the source. Note that the file extension is omitted. In this case, both the world.shp and world.dbf files will be parsed. Add the .shp or .dbf extension if you need to parse a certain file. The second argument specifies the precision of the resulting shape coordinates. Within the callback function, which comes as the third argument, the resulting coordinates are assigned to the mapData option of the dxVectorMap widget.

  • Using Data from an ArrayBuffer Source
    The following code sample demonstrates how to use the parse() method for parsing data from any source of the ArrayBuffer type.

    JavaScript
    var parseSources = { shp: shpArrayBuffer, dbf: dbfArrayBuffer },
        parseOptions = { precision: 2 },
    var data = DevExpress.viz.vectormaputils.parse(parseSources, parseOptions);
    $('#mapContainer').dxVectorMap({
        mapData: data.features
    });

    In this code, the parse(parseSources, parseOptions) method transforms the sources specified by the parseSources object into the format supported by dxVectorMap. Shape coordinates are converted with a precision specified by the parseOptions object.

No matter the way, the resulting shape coordinates can be accessed using the features field of the object returned by the parse() method or the object passed to the callback function. A particular shape attribute can be accessed by its name using the attribute(name) method of a map area.

Node.js Approach

If you develop using the Node.js platform, utilize a special script allowing you to parse binary sources and generate dxVectorMap-compatible files from them. This script can be found in the Lib/js/vectormap-utils folder of the ChartJS zip-archive. Load this script as a module using the following code.

JavaScript
var vectormaputils = require('./dx.vectormaputils.node.js');

The next two subtopics describe the parsing and generating operations in detail.

Parsing

There are two possible ways to parse binary data for dxVectorMap.

  • Using a Shapefile
    If you can access a required shapefile, use the following construction.

    JavaScript
    vectormaputils.parse('/shapeSources/world', { precision: 2 }, function (data) {
        $('#mapContainer').dxVectorMap({
            mapData: data.features
        });
    });

    In this code, the function's first argument specifies the URI of the source. Note that the file extension is omitted. In this case, both the world.shp and world.dbf files will be parsed. Add the .shp or .dbf extension if you need to parse a certain file. The second argument specifies the precision of the resulting shape coordinates. Within the callback function, which comes as the third argument, the resulting coordinates are assigned to the mapData option of the dxVectorMap widget.

  • Using Data from a Buffer Source
    The following code sample demonstrates how to use the parse() method for parsing data from any source of the Buffer type.

    JavaScript
    var parseSources = { shp: shpBuffer, dbf: dbfBuffer },
        parseOptions = { precision: 2 },
    var data = vectormaputils.parse(parseSources, parseOptions);
    $('#mapContainer').dxVectorMap({
        mapData: data.features
    });

    In this code, the parse(parseSources, parseOptions) method transforms the sources specified by the parseSources object into the format supported by dxVectorMap. Shape coordinates are converted with a precision specified by the parseOptions object.

No matter the way, the resulting shape coordinates can be accessed using the features field of the object returned by the parse() method or the object passed to the callback function. A particular shape attribute can be accessed by its name using the attribute(name) method of a map area.

Generating

In addition, you can generate dxVectorMap-compatible files from shapefiles to use them as a data source afterwards. For this purpose, use the processFiles(source, options) method.

JavaScript
var source = 'shapeSources/world.shp',
    options = {
        output: 'destinationFolder',
        precision: 2,
        isJSON: true
    };

vectormaputils.processFiles(source, options);

This method accepts the URI of the source shapefile as the first argument. When a folder is passed as the first argument (instead of a file), all shapefiles from this folder will be processed.

The processFiles(source, options) method accepts processing options as the second argument. These options include:

  • output string
    Specifies a destination folder. This folder should be created in advance. When this option is not specified, the resulting file is placed in the folder where its source shapefile is located.

  • precision numeric
    Specifies a precision for shape coordinates. By default, no precision applies.

  • isJSON boolean
    Specifies the format of the resulting file. When this option is set to true, the resulting file has the '.json' extension and can be used in dxVectorMap as a JSON object. When this option is set to false, the resulting file has the '.js' extension and can be used in dxVectorMap as a script.

You can use the Node.js console for generating files as well. The accepted string has the following format.

node dx.vectormaputils.node.js Source [--output DestinationFolder] [--precision Precision] [--json]

To receive help on the parameters, type the following string in the console.

node dx.vectormaputils.node.js --help

Data for Markers

To provide data for map markers, assign an array of objects to the markers option. Each object of the array should contain the 'coordinates' field, which should be assigned to an array of two values: the first is the longitude, 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 fields you require.

JavaScript
var markersArray = [
{
    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: markersArray
    });
});

You can also specify a data source for markers from a JSON object. For this purpose, assign the URL of this object to the markers option.

Show Example:
jQuery
<div id="mapContainer" style="height:500px; max-width:800px; margin: 0 auto"></div>
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' }
    }, {
        coordinates: [-84.2533, 30.455],
        attributes: { name: 'Tallahassee' }
    }, {
        coordinates: [-89.65, 39.783],
        attributes: { name: 'Springfield' }
    }
];

$(function () {
    $('#mapContainer').dxVectorMap({
        mapData: '/Content/data/vectorMap-sources/usa.txt',
        bounds: {
            minLon: -135, maxLon: -65,
            minLat: 20, maxLat: 60
        },
        zoomFactor: 1.25,
        areaSettings: { hoverEnabled: false },
        markerSettings: {
            customize: function (m) {
                return { text: m.attributes.name }
            },
            font: { size: 11 }
        },
        markers: markers
    });
});