Fork me on GitHub

MAPSTRACTION

The Javascript Mapping Abstraction Library

Loading The Map

Because of the differing ways that the mapping libraries that Mapstraction supports load a map into your web page, it’s highly advisable to place your code inside a function which is called when the page has completed loading and also to wrap the code which produces and manages your map inside a try ... catch exception handling block.

Assuming you place your maps initialisation code into a function called load_map, in plain Javascript, you’d call your function from within a window.load event handler.

window.onload = function() {
	load_map();
};

If you’re using jQuery, you’d call your function from within a $(document).ready() event handler.

$(document).ready(function() {
	load_map();
});

If you’re using Dojo, you’d call you function from within a dojo.addOnLoad() event handler.

dojo.addOnLoad(function() {
	load_map();
});

For more information on Mapstraction exceptions, see the Exceptions tutorial and for more information on mapping provider specific gotchas see the Map Provider Gotchas page on the Mapstraction wiki.

Choose And Load Your Map Provider And Mapstraction

Before you can create a map with Mapstraction, you’ll need to choose which map provider you want to use. You’ll need to know 3 things …

  1. The Mapstraction provider id
  2. The JavaScript source and any other source file, such as CSS, you’ll need to use to include your map provider into your web page
  3. Whether your chosen mapping provider requires authentication via a key or token(s)

All of this information can be found on the Mapstraction Wiki on the Supported Map Providers page.

So, if you want to create a map using OpenLayers, you’d need to include the following into your web page’s header…

<script type="text/javascript" src="http://dev.openlayers.org/releases/OpenLayers-2.9.1/OpenLayers.js"></script>

OpenLayers doesn’t require any additional source files or an application key, so for this provider you should be good to go

If you wanted to use Leaflet, you’d need both the following CSS and JavaScript to be in your page’s header …

<link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.6.2/leaflet.css" />
 <!--[if lte IE 8]>
     <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.6.2/leaflet.ie.css" />
 <![endif]-->
<script src="http://cdn.leafletjs.com/leaflet-0.6.2/leaflet.js"></script>

Or, if you wanted to use Nokia’s HERE maps, you’d need a HERE Developer account which will give you an application id and authentication token, so you’d need the following in your page’s header …

<meta http-equiv="X-UA-Compatible" content="IE=7; IE=EmulateIE9" />
<script src="http://api.maps.nokia.com/2.2.1/jsl.js" type="text/javascript" charset="utf-8"></script>
<script type="text/javascript">
nokia.Settings.set ("appId", "[your-app-id-here]");
nokia.Settings.set ("authenticationToken", "[your-auth-token-here]");
</script>

Finally, with our map provider’s API loaded and knowing the Mapstraction provider id, you can load Mapstraction itself and tell it which provider to use. So, for OpenLayers you’d add the following to your page’s header …

<script src="http://mapstraction.com/mxn/build/latest/mxn.js?(openlayers)" type="text/javascript"></script>

… using leaflet or nokia or whatever provider you’ve chosen to use.

Now, armed with this information, you can create a basic web page containing the map of your choice.


Using The Right Mapstraction Version


To use the latest stable release of Mapstraction, always either host your own copy of Mapstraction or pull the code from http://mapstraction.com/mxn/build/latest/mxn.js. If you want to live life on the bleeding edge, the current development version of Mapstraction is found at http://mapstraction.com/mxn/build/dev/mxn.js

Do not, under any circumstances try to pull Mapstraction directly from the project’s GitHub repository, via https://raw.github.com/mapstraction/.... GitHub have recently made some changes to the way in which they serve up content from raw.github.com and things may and probably will break.

And now on to making a map …


A Basic Map Using OpenLayers


Taking all the information from the previous section, you can now put together your web page. Firstly, you’ll need to include the provider Javascript files into your page’s header.

<script src="http://openlayers.org/api/OpenLayers.js"></script>

Then include the Mapstraction Javascript file, telling Mapstraction which provider you’ll be using.

<script src="http://mapstraction.com/mxn/build/latest/mxn.js?(openlayers)" type="text/javascript"></script>

You’ll need to supply an HTML div element which will contain your map.

<div id="map"></div>

The map’s div will need to have its dimensions defined in CSS.

<style type="text/css">
#map {
	height: 400px;
}
</style>

Finally, you’ll create a Mapstraction object, telling Mapstraction the id of the map div and the provider id and setting the initial centre of the map.

<script type="text/javascript">
 var map = new mxn.Mapstraction('mapdiv', 'openlayers'); 
 var latlon = new mxn.LatLonPoint(39.74,-104.98);
 map.setCenterAndZoom(latlon, 10);
</script>

Putting It All Together

The code for your web page should not look something like this

<html>
<head>
   	<title>Mapstraction Simple Example</title>
   	<script src="http://openlayers.org/api/OpenLayers.js"></script>
   	<script src="http://mapstraction.com/mxn/build/latest/mxn.js?(openlayers)" type="text/javascript"></script>
	<style type="text/css">
	#map {
		height: 400px;
	}
	</style>
</head>
<body>
	<div id="map"></div>
	<script type="text/javascript">
		var map = new mxn.Mapstraction('map', 'openlayers'); 
		var latlon = new mxn.LatLonPoint(51.50733, -0.12769);

		map.setCenterAndZoom(latlon, 10);
	</script>
</body>
</html>

And you should see a map, like the one below, in your browser and centred on London’s Charing Cross.

Changing Map Providers

One of the key things about Mapstraction is that you can change your mapping provider without having to rewrite the vast majority of your code. So to change the example above from using OpenLayers to using Leaflet, is as simple as replacing the OpenLayers Javascript include with those needed by Leaflet.

<link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.6.2/leaflet.css" />
<!--[if lte IE 8]>
    <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.6.2/leaflet.ie.css" />
<![endif]-->
<script src="http://cdn.leafletjs.com/leaflet-0.6.2/leaflet.js"></script>

And telling Mapstraction to use Leaflet rather than OpenLayers

var map = new mxn.Mapstraction('map', 'leaflet');

After reloading your web page in your browser, you should now see the same map, but this time displayed using Leaflet and not OpenLayers.