Wax is your gateway into putting maps on the web. It makes it easier to use APIs like Modest Maps, and documents, from the very start, the basics of web maps.
If you’re just starting out, follow along and by the end, you’ll be a web-mapping pro.
<div id='intro-map'></div>
<script>
var mm = com.modestmaps;
var url = 'http://tiles.mapbox.com/mapbox/api/Tileset/geography-class';
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(m);
});
</script>
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 the instructions below for each mapping API (Modest Maps, Leaflet, Google Maps, OpenLayers) to include Wax in your project.
Suppose you’re making cool map designs with TileMill or you want to pre-built maps from MapBox, 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:
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.
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.js
contains the Modest Maps library.wax/dist/wax.mm.js
contains the Wax controls and integration code for
Modest Maps.wax/theme/controls.css
contains 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.
<div id="modestmaps-setup"></div>
<script>
var tilejson = {
tilejson: '1.0.0',
scheme: 'tms',
tiles: ['http://a.tiles.mapbox.com/mapbox/1.0.0/world-light/{z}/{x}/{y}.png']
};
// Alias com.modestmaps to mm. This isn't necessary -
// just nice for shorter code.
var mm = com.modestmaps;
// 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(new mm.Location(39, -98), 2);
</script>
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.
To start you’ll need to know the URL of the tileset you want to use. Most
tilesets follow the convention of ending in /{z}/{x}/{y}.[image format]
where {z}
is the zoom level, {x}
is the x coordinate and {y}
is
the y coordinate. TileJSON represents tileset URLs using these placeholders
so that a tile at any coordinate can be requested.
The URL of the tile above is http://a.tile.mapbox.com/1.0.0/world-light/2/2/2.png
.
By inference we can write the TileJSON needed to use the World Light tileset:
{
"version": "1.0.0",
"scheme": "tms",
"tiles" ["http://a.tile.mapbox.com/1.0.0/world-light/{z}/{x}/{y}.png"]
}
version
key declares that we are implementing version 1.0.0
of the
TileJSON spec. Since there’s only one version of TileJSON so far, it’ll be 1.0.0
for you, too.scheme
key defines the order in which tiles are saved. Don’t worry about this –
for all tilesets that have 1.0.0
in the URL, this’ll be tms
tiles
key contains an array of URLs from which tiles can be requested. Pro users
multiple tile URLs here so that they can request tiles from multiple domains simultaneously.Some servers, like TileStream provide TileJSON definitions for all of the tilesets they serve. This way, it’s easy to configure maps, since all you need to know is the URL of the TileJSON file, and that’ll provide you with values for urls, a centerpoint, zoom ranges, and more. Wax contains a helper function that just pulls a TileJSON description from a server using JSONP and gives it to you as an argument to a callback function that you can use to configure your map.
Here we’re using the url http://tiles.mapbox.com/mapbox/api/Tileset/dc-nightvision
for
the TileJSON for dc-nightvision – using the TileStream API. These are also available off of tilesets
in layer.json
files. As an example, http://a.tiles.mapbox.com/mapbox/1.0.0/dc-nightvision/0/0/0.png
has a TileJSON definition at http://a.tiles.mapbox.com/mapbox/1.0.0/dc-nightvision/layer.json
var url = 'http://tiles.mapbox.com/mapbox/api/Tileset/dc-nightvision';
wax.tilejson(url, function(tilejson) {
var mm = com.modestmaps;
var m = new mm.Map('tilejson-url',
new wax.mm.connector(tilejson),
new mm.Point(240,120));
m.setCenterZoom(new mm.Location(
tilejson.center[1], // lon
tilejson.center[0]), // lat
tilejson.center[2]); // zoom
});