Wednesday, September 4, 2013

How to customize jVectorMap region popups

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

In the previous posting in this series, we explored how to integrate data with jVectorMap. In this posting, we'll explore how to customize jVectorMap region popups. It will cover several customization topics, including: customizing the country / region popup text and adding country flag images to the popup. This article builds upon the work explored in the first and second articles of this series, and it will employ the same jQuery and jVectorMap versions used previously. 

Customizing country/region popup text

For the simplest implementation of a jVectorMap display, the popups that appear when hovering the cursor over a specific region are the country/region name.  This name value is embedded in the vector map data file.  For example, consider the vector mapping for Sweden:
"SE": {"path": "M476.42,90.44l-0.15,0.1l-2.43,2.86l-0.07,0.24l0.36, 2.31l-3.84,3.1l-4.83, 3.38l-0.11,0.15l-1.82, 5.45l0.03,0.26l1.78, 2.68l2.27,1.99l-2.13,3.88l-2.49,0.82l-0.2,0.24l-0.95,6.05l-1.32, 3.09l-2.82, -0.32l-0.3, 0.16l-1.34, 2.64l-2.48,0.14l-0.76,-3.15l-2.09,-4.04l-1.85, -5.01l1.03, -1.98l2.06, -2.53l0.06,-0.13l0.83, -4.45l-0.06, -0.25l-1.54, -1.86l-0.15, -5.0l1.52, -3.48l2.28,0.06l0.27, -0.16l0.87,-1.59l-0.01, -0.31l-0.8,-1.21l3.79,-5.63l4.07,-7.54l2.23, 0.01l0.29, -0.22l0.59, -2.15l4.46,0.66l0.34, -0.26l0.34, -2.64l1.21,-0.14l3.24,2.08l3.78, 2.85l0.06, 6.37l0.03, 0.14l0.67, 1.29l-3.95,1.07Z", "name": "Sweden"},
The value for the name string is what is displayed in the popup. 
To customize the popup name, you could revise the value associated with the name string for any country.  Another way is to override the event handler for the popup display, and this is what we'll show here. There are a couple of events triggered when you move the cursor over a region: onRegionOver & onRegionLabelShow.   The one we'll need to override is onRegionLabelShow.  Highlighted below is the code you need to add.  I've added a bit more to the label property in order to extract the actual value associated with the string/value pair in cdata.
//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
       }]
     },
    onRegionLabelShow: function(event, label, code){
       label.html(label.html() +' (' + code.toString() + 
      ') <br>Count: ' + cdata[code]);
     },
    });
    setInterval(function(){
      $.getJSON('data/cdata2.json', function(cdata){
        var map = $('.map1').vectorMap('get', 'mapObject');
        map.series.regions[0].setValues(cdata);
      })
    }, 10000); 
})
Inserting this event handler into the code you developed previously (for the second article of this series), you now get a bit more when you hover over the target country:
Note however that hovering over any other region returns an undefined message.
This is because your data array does not contain values associated with that country.  To address that, check the type before using it.  For example, here's one function that resolve this problem:
function chkValue(val){
    if (typeof val ==="undefined"){
      x = 0;
    }
    else {
      x = val;
    }
    return x;
};
Add this function, or anything similar, and the popup message is cleaned up:
Be sure to add this and other such utility functions immediately after the getJSON container statement.

Add country flag images to region popups

Adding the country flag images to the popups involves a few preparatory steps:
  1. Generating a list of country names and their digraphs.
  2. Collating a batch of country flag images.
  3. Modifying flag image file names to their diagraph codes.
onRegionLabelShow: function(event, label, code){ 
   label.html('<img src="/jVectorMap/CountryFlags/' + code.toString() + ".png" /> ' + label.html() + '<hr noshade="noshade" style="height: 1px"/>Count: ' + chkValue(cdata[code]));
}
Add this event handler script within the statement generating the vector map $('.map1').vectorMap({. After refreshing the browser, the new popup can be seen
Summary

In this article, you learned how to customize the country/region popup contents by overriding the onRegionLabelShow event handler.  In the next article of this series, we'll explore adding user interactivity to the UI.

References

3 comments:

Anonymous said...

Thanks for these nice tutorials however the onRegionLabelShow doesn't work (maybe because of some update). There is however onRegionTipShow that takes the same parameters and that seemed to work for me

Anonymous said...

If you have trouble with onRegionLabelShow maybe you should use onRegionTipShow. Perhaps due to an update. Thanks for these cool step by step tutorial theyre' awesome

erational said...

the event have been renommed

you have to call onRegionTipShow