Wax
MapBox has introduced MapBox.js v1, which features improved browser support, documentation, and access to a rich ecosystem of Leaflet plugins. You might want to consider using it for any new projects.
This version of Wax has been customized to work with additional functionality added to TileMill, mainly around enhancing the bounding box when Exporting a static map.
If you’re just starting out, follow along and by the end, you’ll be a web-mapping pro.
Wax in Action
Here is a map demo of Wax showing the world, with a Country and Map popup when you hover over a country.
<div id='intro-map'></div>
var url = 'https://api.tiles.mapbox.com/v3/mapbox.geography-class.jsonp';
wax.tilejson(url, function(tilejson) {
var m = new MM.Map('intro-map',
new wax.mm.connector(tilejson),
new MM.Point(700,400));
m.setCenterZoom(new MM.Location(tilejson.center[1],
tilejson.center[0]),
tilejson.center[2] - 3);
wax.mm.zoomer(m).appendTo(m.parent);
wax.mm.interaction()
.map(m)
.tilejson(tilejson)
.on(wax.tooltip().animate(true).parent(m.parent).events());
});
Get Wax
To follow this quick tutorial, you’ll need a copy of Wax: unlike Google Maps, it’s a Javascript library you copy to your server, so you have control over it.
If you just want to download the source code for Wax, get a zip file from GitHub. If you want to develop Wax, or keep it up to date more easily, check out the project from GitHub with git.
See Making Your First Map below for instructions on how to include Wax in your project.
A Quick Intro
Suppose you’re making cool map designs with TileMill or you want to use maps from MapBox Hosting, and you want to get famous by putting them somewhere online - your blog, a big CMS, or anywhere else.
Don’t be afraid! It’s not too hard to do, and once you’ve learned how to do it, you’ll have the power to make super-custom maps with minimal effort.
So your ingredients will be:
- A map server, like TileStream or MapBox Hosting. All of the examples you’ll see here use MapBox Hosting, so you can copy & paste at will and it’ll all work.
- A Javascript API, like Modest Maps
- Wax
- Your website
The mapping server serves up tiles of rendered data - tiles being 256 pixel square images covering some of the world. Here’s a tile of Europe from the World Light tileset.
Of course, things will get a lot cooler than this: Wax lets you use your own tiles, add zoom buttons, interaction, and a lot more. But it all starts out with tiles.
Making Your First Map
The first step is to download and include the necessary Javascript code to make your map work. We’ll also include a CSS file to start rolling with style:
wax/ext/modestmaps.min.jscontains the Modest Maps library.wax/dist/wax.mm.jscontains the Wax controls and integration code for Modest Maps.wax/theme/controls.csscontains default styles for controls. You can always swap in your own later on.
<html>
<head>
<script src='wax/ext/modestmaps.min.js' type='text/javascript'></script>
<script src='wax/dist/wax.mm.js' type='text/javascript'></script>
<link href='wax/theme/controls.css' rel='stylesheet' type='text/css' />
...
Here’s your first map! If you’ve downloaded Wax and add the code above into the
<head> of your page, then you can put the following code into the
<body> of your page, and you’ll get a map! Go ahead and
drag around the little map below -
Modest Maps is making the tiles move when you click and drag.
var url = 'https://api.tiles.mapbox.com/v3/mapbox.world-light.jsonp';
wax.tilejson(url, function(tilejson) {
// Set up a map in a div with the id 'modestmaps-setup'
var m = new MM.Map('modestmaps-setup',
// Use Wax's connector to add a new custom layer
new wax.mm.connector(tilejson),
// And it'll be 240px by 120px
new MM.Point(240,120));
// Center it on the United States, at zoom level 2.
m.setCenterZoom({ lat: 39, lon: -98 }, 2);
});
Let’s look at how that was done: the only thing on the page besides that
<script> tag and its code is a <div>
tag with the id modestmaps-setup. And, down below, you see the code
var m = new MM.Map('modestmaps-setup' //
So, you’re telling Modest Maps, MM, to create a new map contained by
this div element. It then does the work of putting a lot of images on the page
and lining them up.
What’s this tilejson variable?
TileJSON is a way of
describing the basic stuff about a map - where tiles are, how they’re
named, and optionally a lot more, like available zoom levels and legends.
Down the line, TileJSON will make your life a lot easier by letting you skip a lot of steps of configuring maps, but we’ll explain it in detail first.