JQVMap is a jQuery plugin that renders Vector Maps. It uses resizable Scalable Vector Graphics (SVG) for modern browsers like Firefox, Safari, Chrome, Opera and Internet Explorer 9. Legacy support for older versions of Internet Explorer 6-8 is provided via VML.
While initializing a map you can provide parameters to change its look and feel.
jQuery('#vmap').vectorMap(
{
map: 'world_en',
backgroundColor: '#a5bfdd',
borderColor: '#818181',
borderOpacity: 0.25,
borderWidth: 1,
color: '#f4f3f0',
enableZoom: true,
hoverColor: '#c9dfaf',
hoverOpacity: null,
normalizeFunction: 'linear',
scaleColors: ['#b6d6ff', '#005ace'],
selectedColor: '#c9dfaf',
selectedRegion: null,
showTooltip: true,
onRegionClick: function(element, code, region)
{
var message = 'You clicked "'
+ region
+ '" which has the code: '
+ code.toUpperCase();
alert(message);
}
});
map - world_en Map you want to load. Must include the javascript file with the name of the map you want. Available maps with this library are world_en, usa_en, europe_en and germany_en
backgroundColor - #a5bfdd Background color of map container in any CSS compatible format.
borderColor - #818181 Border Color to use to outline map objects
borderOpacity - 0.5 Border Opacity to use to outline map objects ( use anything from 0-1, e.g. 0.5, defaults to 0.25 )
borderWidth - 3 Border Width to use to outline map objects ( defaults to 1 )
color - #f4f3f0 Color of map regions.
colors Colors of individual map regions. Keys of the colors objects are country codes according to ISO 3166-1 alpha-2 standard. Keys of colors must be in lower case.
enableZoom - boolean Whether to Enable Map Zoom ( true or false, defaults to true)
hoverColor - #c9dfaf Color of the region when mouse pointer is over it.
hoverOpacity - 0.5 Opacity of the region when mouse pointer is over it.
normalizeFunction - 'linear' This function can be used to improve results of visualizations for data with non-linear nature. Function gets raw value as the first parameter and should return value which will be used in calculations of color, with which particular region will be painted.
scaleColors - ['#b6d6ff', '#005ace'] This option defines colors, with which regions will be painted when you set option values. Array scaleColors can have more then two elements. Elements should be strings representing colors in RGB hex format.
selectedRegion - mo This is the Region that you are looking to have preselected (two letter ISO code, defaults to null )
Region Names & Codes
showTooltip - boolean Whether to show Tooltips on Mouseover ( true or false, defaults to true)
onLabelShow - function(element, label, code) Callback function which will be called before label is shown. Label DOM object and country code will be passed to the callback as arguments.
onRegionOver - function(element, code, region) Callback function which will be called when the mouse cursor enters the region path. Country code will be passed to the callback as argument.
onRegionOut - function(element, code, region) Callback function which will be called when the mouse cursor leaves the region path. Country code will be passed to the callback as argument.
onRegionClick - function(element, code, region) Callback function which will be called when the user clicks the region path. Country code will be passed to the callback as argument.
Dynamic Updating
Most of the options can be changed after initialization using the following code:
jQuery('#vmap').vectorMap('set', 'colors', {us: '#0000ff'});
Instead of colors can be used any parameter except callbacks. Callbacks can be added and deleted using standard jQuery patterns of working with events.
You can define callback function when you initialize JQVMap:
jQuery('#vmap').vectorMap(
{
onLabelShow: function(event, label, code)
{
},
onRegionOver: function(event, code, region)
{
},
onRegionOut: function(event, code, region)
{
},
onRegionClick: function(event, code, region)
{
}
});
Or later using standard jQuery mechanism:
jQuery('#vmap').bind('labelShow.jqvmap',
function(event, label, code)
{
}
);
jQuery('#vmap').bind('regionMouseOver.jqvmap',
function(event, code, region)
{
}
);
jQuery('#vmap').bind('regionMouseOut.jqvmap',
function(event, code, region)
{
}
);
jQuery('#vmap').bind('regionClick.jqvmap',
function(event, code, region)
{
}
);
Consider that fact that you can use standard features of jQuery events like event.preventDefault() or returning false from the callback to prevent default behavior of JQVMap (showing label or changing country color on hover). In the following example, when user moves mouse cursor over Canada label won't be shown and color of country won't be changed. At the same label for Russia will have custom text.
jQuery('#vmap').vectorMap(
{
onLabelShow: function(event, label, code)
{
if (code == 'ca')
{
event.preventDefault();
}
else if (code == 'ru')
{
label.text('Bears, vodka, balalaika');
}
},
onRegionOver: function(event, code)
{
if (code == 'ca')
{
event.preventDefault();
}
},
});
Data Visualization
Here I want to demonstrate how visualization of some geographical-related data can be done using JQVMap. Let's visualize information about GDP in 2010 for every country. At first we need some data. Let it be site of International Monetary Fond. There we can get information in xsl format, which can be converted first to csv and then to json with any scripting language. Now we have file gdp-data.js with such content (globals are evil, I know, but just for the sake of simplification):
var sample_data = {"af":16.63,"al":11.58,"dz":158.97,...};
Then connect it to the page and add some code to make visualization:
var max = 0,
min = Number.MAX_VALUE,
cc,
startColor = [200, 238, 255],
endColor = [0, 100, 145],
colors = {},
hex;
//find maximum and minimum values
for (cc in gdpData)
{
if (parseFloat(gdpData[cc]) > max)
{
max = parseFloat(gdpData[cc]);
}
if (parseFloat(gdpData[cc]) < min)
{
min = parseFloat(gdpData[cc]);
}
}
//set colors according to values of GDP
for (cc in gdpData)
{
if (gdpData[cc] > 0)
{
colors[cc] = '#';
for (var i = 0; i<3; i++)
{
hex = Math.round(startColor[i]
+ (endColor[i]
- startColor[i])
* (gdpData[cc] / (max - min))).toString(16);
if (hex.length == 1)
{
hex = '0'+hex;
}
colors[cc] += (hex.length == 1 ? '0' : '') + hex;
}
}
}
//initialize JQVMap
jQuery('#vmap').vectorMap(
{
colors: colors,
hoverOpacity: 0.7,
hoverColor: false
});
Custom Maps
For information on building your own custom maps to use with this library, check out our Github project at https://github.com/manifestinteractive/jqvmap
