Fork me on GitHub

jQuery Mapael - Build dynamic vector maps


#Overview

jQuery Mapael is a jQuery plugin based on raphael.js that allows you to display dynamic vector maps.

For example, with Mapael, you can display a map of the world with clickable countries. You can build simple dataviz by setting some parameters in order to automatically set a color to each area of your map and generate the legend. Moreover, you can plot cities on a map with their latitude and longitude.

As Raphaël, Mapael supports Firefox 3.0+, Safari 3.0+, Chrome 5.0+, Opera 9.5+ and Internet Explorer 6.0+.

To download mapael, go to the GitHub repository. Additional maps are stored in the repository 'neveldo/mapael-maps'.

Key features

#How to use Mapael

Here is the simplest example that shows how to display an empty map of the world :

HTML :

<div class="container">
	<div class="map">Alternative content</div>
</div>
            

JS :

$(".container").mapael({
    map : {
        name : "world_countries"
    }
});
            

Result :

#Examples

#API reference (version 0.7.0)

All options are provided as an object argument of the function $.fn.mapael(Object options). Some of them have a default value. If you want to redefine these default values, you can overload the variable $.fn.mapael.defaultOptions.

Parameter 'options' :

#Update the map data

Update map data is as simple as triggering an 'update' event on the map container with new data provided as argument. All attributes from plots and areas can be updated (including their related text, contents of the tooltips , ...).
Update the values of plots and areas connected to a legend will automatically update their attributes according their new slices.

$(".container").trigger('update', [updatedOptions, newPlots, deletedPlots, opt]);

Here is examples of refreshable map : dataviz example, Misc attributes updated on the map of France

#Extend Mapael

Mapael can easily be extended with two hooks.

afterInit : function(container, paper, areas, plots, options) {...}

This hook is called after the initialization of the map.

afterUpdate : function(container, paper, areas, plots, options) {...}

This hook is called after each update of the map ('update' event triggered).

Here is an example of use with the afterInit hook that allows to position images on the map : afterInit example

#Zoom feature

Mapael allows you to trigger an event 'zoom' on the map container.

$(".mapContainer").trigger("zoom", zoomLevel, x, y);

The current zoom level can be retrieved with the data "ZoomLevel"

$(".mapContainer").data("zoomLevel")

Here is an example of use of the "zoom" event : Zoom example

#How to create new maps ?

Maps for the world, France and USA countries are available with Mapael. It's easy to create new maps, so feel free to add new ones. The first step is to retrieve the SVG file of the wanted map. You can find this kind of resources on Natural Earth Data or Wikimedia Commons. If necessary, SVG files can be edited with dedicated tools like Inkscape. Then, you have to create a new JS file from this template :

(function($) {
                $.extend(true, $.fn.mapael, 
                    {
                        maps :{
                            yourMapName : {
                                width : 600,
                                height : 500,
                                getCoords : function (lat, lon) {
                                    // Convert latitude,longitude to x,y here
                                    return {x : 1, y : 1};
                                }
                                elems : {
                                    // List of SVG paths for building the map
                                }
                            }
                        }
                    }
                );
            })(jQuery);
            

You have to set the default width and height of your map. If you want to plot cities, you will have to customize the getCoords() function that takes as arguments a latitude and a longitude, and returns x,y coordinates depending on the map projection (mercator, miller, ...). Then, the last step is to open the SVG image with a text editor and copy the paths definitions into the "elems" parameter. In order to use your new map, you need to load the JS file, and set 'yourMapName' for the Mapael 'name' parameter.

Additional maps are stored in the repository 'neveldo/mapael-maps'.