Wednesday, September 4, 2013

How to integrate data with jVectorMap

jVectorMap Series 
How to Build a Simple jVectorMap Display
How to integrate data with jVectorMap
How to customize jVectorMap region popups
How to add user interactivity to jVectorMap
How to add a popup modal to jVectorMap using Bootstrap
How to integrate jVectorMap with SharePoint 2010
How to integrate SharePoint 2010 list data with jVectorMap
How to use REST to integrate SharePoint 2010 list data with jVectorMap
How to use SOAP to integrate SharePoint 2010 list data with jVectorMap
Introduction

Country/Region data can be integrated with a jVectorMap display and presented uniquely for each country using all of the standard JavaScript methods.  Here, we will explore two: simple arrays (either local or stored in a separate file) and JSON; and we will explore automated refresh of the data.  This article builds upon what was learned in the first article on jVectorMap.  The versions of jQuery and jVectorMap remain the same.

Integrating Country Data

Country/Region data is introduced into the map through the series object, which has two sub-objects, series and regions.  The regions object contains a number of properties for specifying data on map regions.  We'll be using the values property of the regions object to pass country data into the vector map to enable unique colors to be specified for each country/region.
  • regions (object)
    • values (array): set this to the array of country diagraphs and values for your application.  Through this property you will be passing your country/region data.  The array must be in the format of a JSON string/value object, where the string will be the country/region digraph and the value will be numeric.
    • scale (array): set this to an array of color values that map the range of country/region data to a color scale.
    • attribute (string): this property controls how the coloration indicated above is applied - fill, stroke, etc
    • normalizeFunction (string): this property controls the type of function used to perform the mapping between the data range and color scale - linear, polynomial, etc
    • min (number): the minimum value of the data range - if not provided, is calculated automatically
    • max (number): the maximum value of the data range - if not provided, is calculated automatically
Integration using a local array

Highlighted below is the modification to the script from the first article in this series. The highlighted portion was added:
<script>
//Define an array object of string/value pairs:
//US: United States
//NO: Norway
//SE: Sweden
//GB: Great Britain
//ES: Spain  
var cdata = {"US": "35", "NO": "15", "SE": "17", "GB": "20", "ES": "10"}
$(function(){
  $('.map1').vectorMap({
   map: 'world_mill_en',
   series: {
     //this is the object for passing country/region data into
     regions: [{
       //define the range of color values
       scale: ['#DEEBF7', '#08519C'],
       //define the function that maps data to color range
       normalizeFunction: 'linear',
       //define the coloration method
       attribute: 'fill',
       //define the array of country data
       values: cdata
     }]
   },
  });
})
</script>
The result of adding this bit of script is shown in the image below.  Coloration is now displayed for just those countries represented in the local array.  Add to the array to display coloration for additional countries.
Integration using a file-based array

The next step is to move the array out of the main page and into a JavaScript file.  To do this, first create a new JS file, and then copy and paste into this file the variable declaration.
Next, comment out the variable declaration in the web page, and then add another script reference in the header of this page:
<!-- data -->
<script src="data/cdata.js"></script>
Then refresh the page.  The same countries will be highlighted as before.

Integration using JSON

JSON is a simple format for data interchange. It's a way of serializing an object in a text-based file and enables the exchange of data between two very different systems.  To employ this method, go back to the JS file you created, save it under a different file name, and then remove the JavaScript from this file so that it contains just the data enclosed in brackets:

Next, remove the js file include that you added previously:
<!-- data -->
<script src="data/cdata.js"></script>
Then, replace the $(function()... statement highlighted below with the getJSON statement also highlighted. The closing brackets remain the same.  All other markup also remains the same
//Define an array object of string/value pairs
//var cdata = {"US": "35", "NO": "15", "SE": "17", "GB": "20", "ES": "10"}
//$(function(){
$.getJSON('data/cdata2.json', function(cdata){
  $('.map1').vectorMap({
    map: 'world_mill_en',
    series: {
      //this is the object for passing country/region data into
      regions: [{
        //define the range of color values
        scale: ['#DEEBF7', '#08519C'],
        //define the function that maps data to color range
        normalizeFunction: 'linear',
        //define the coloration method
        attribute: 'fill',
        //define the array of country data
        values: cdata
      }]
    },
  });
})
Lastly, refresh the page: the same countries will be highlighted as before.

Automated Data Refresh

The JSON data can be automatically refreshed at predefined intervals using JavaScript timing events, using either the setInterval or setTimeout functions.  This example will employ setInterval.  To do this, we'll add a single function block within the .getJSON container (highlighted):
//Define an array object of string/value pairs
//var cdata = {"US": "35", "NO": "15", "SE": "17", "GB": "20", "ES": "10"}
//$(function(){
$.getJSON('data/cdata2.json', function(cdata){
  $('.map1').vectorMap({
    map: 'world_mill_en',
    series: {
      //this is the object for passing country/region data into
      regions: [{
        //define the range of color values
        scale: ['#DEEBF7', '#08519C'],
        //define the function that maps data to color range
        normalizeFunction: 'linear',
        //define the coloration method
        attribute: 'fill',
        //define the array of country data
        values: cdata
      }]
    },
  });
  setInterval(function(){
    $.getJSON('data/cdata2.json', function(cdata){
      var map = $('.map1').vectorMap('get', 'mapObject');
      map.series.regions[0].setValues(cdata);
    })
  }, 10000);
})
This works by creating a new instance of the existing vector map object, and then updating the country values for that map object.  It updates at 10s intervals.  You can test this by making a change to the JSON data file, cdata2.json, saving it, and then noticing the affect on the vector map in your browser.

Summary

This article builds upon the first article by showing you simple methods for integrating country data into a jVectorMap display.  In the next article, we will explore customizing the country/region popups and a few other minor enhancements.
 
References

2 comments:

Anonymous said...

Good article. Thank you to share.

Anonymous said...

Thanks! Its simply works!