jQuery Mapael

jQuery Mapael 1.1.0 Whats new ?

Ease the build of pretty data visualizations on dynamic vector maps

Map with some plotted cities, areas and zoom enabled. Try on JSFiddle »

Map with a legend for areas. Try on JSFiddle »

Map with a legend for plotted cities. Try on JSFiddle »

Map with multiple plotted cities legends that handle different criteria. Try on JSFiddle »

Dataviz example : evolution of the population by country through the years. Try on JSFiddle »

Map with links between the plotted cities. Try on JSFiddle »

Download version 1.1.0

#Overview

Friends

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 also build simple dataviz by setting some parameters in order to automatically set a color depending on a value to each area of your map and display the associated legend. Moreover, you can plot cities on the map with circles, squares or images by their latitude and longitude. Many more options are available, read the documentation in order to get a complete overview of mapael abilities.

Mapael supports all modern browsers and Internet Explorer 9+. For older versions of IE, you can load jQuery 1.11.x and Raphael.js 2.1.2 as dependencies, most of the jQuery Mapael features should work fine.

Click here to download the lastest stable release of Mapael from GitHub. Additional maps are stored in the repository 'neveldo/mapael-maps'.

Key features

#Basic code example

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>

Javascript

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

Result

#Examples

Basic

Advanced

#API reference (version 1.1.0)

All options are provided as an object argument of the function $.fn.mapael(Object options). Many of them have a default value. Default values are stored in the variables $.fn.mapael.defaultOptions and $.fn.mapael.legendDefaultOptions. If you want to re-define them, you can overload these two variables.

Through these mapael options, you can load a map (such as the world map, the USA map, or your own map) and customize the attributes of areas (such as the background-color, the tooltip content, link, text, attributes on mouseover, jquery events, etc). You can plot points on the map by latitude and longitude or x and y and set their attributes. You can add curved links between two points. You can enable the zoom feature that allow to zoom the map through the buttons or through the mousewheel. You can define legends for areas and/or plotted points in order to apply automatically some attributes to the elements of the map depending on the associated value. Here is the complete API documentation.

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 plotted points and areas can be updated (including their related text, contents of the tooltips , ...).
Update the values of plotted points 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 several hooks and events.

Hook map.beforeInit

beforeInit : function(container, paper, options) {...}

This hook is called before the initialization of the map, right after the display of the areas.

Hook map.afterInit

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

This hook is called after the initialization of the map.

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

Hook afterUpdate

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

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

Event afterZoom

This event is triggered after a zoom action on the map. The event brings these data :

Event afterPanning

This event is triggered after a panning action on the map. The event brings these data :

#Zoom feature

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

$(".mapContainer").trigger("zoom", options);

options (Object) : Zoom options. The point to focus on can be set by latitude and longitude or by x and y coordinates.

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

$(".mapContainer").data("zoomLevel");
$(".mapContainer").data("panX");
$(".mapContainer").data("panY");
$(".mapContainer").data("zoomX");
$(".mapContainer").data("zoomY");

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

#Create your own vector map for jQuery Mapael

A complete tutorial that explains you how to create your own vector map for jQuery Mapael is available here.
Some usefull online tools are available to ease the work :

If you need a special integration of jQuery Mapael in your application, a custom feature or map, feel free to contact me at contact{at}vincentbroute{dot}fr.

Copyright (C) 2013 - 2015 Vincent Brouté - Released under MIT license