jQuery Mapael

jQuery Mapael 2.2.0
Released on March 08, 2018, what's new ?

Ease the build of pretty data visualizations on dynamic vector maps

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

Map with a legend for areas. Try it »

Map with a legend for plotted cities. Try it »

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

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

Map with links between the plotted cities. Try it »

Download the latest version (2.2.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

#Code examples

The basic examples only involve to call Mapael with a simple configuration object whereas advanced examples show advanced features or more complex integration of Mapael.

Basic

Advanced

#API reference (version 2.2.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 $.mapael.prototype.defaultOptions and $.mapael.prototype.legendDefaultOptions (Overriding default options example). 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', [options]);

Here is examples of refreshable map : dataviz example, Misc attributes updated on the map of France, Map with some updates on links performed

#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 :

#Filter the elements to show on the map depending on values intervals

The elements to show on the map can be filtered depending on values intervals by triggering a 'showElementsInRange' event on the map container : $(".mapcontainer").trigger("showElementsInRange", [opt]); . Examples : Map with a range selection for plotted cities, Map with a range selection for areas. Available options :

#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, by x and y coordinates or with an area ID. The following options are available :

  Or Or

The current zoom data can be retrieved with the data from "zoomData" key :

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

Here are some examples of use of the "zoom" event : Zoom on specific areas, Zoom on click

#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 - 2018 Vincent Brouté - Released under MIT license