Wax: Custom, Advanced UI for Web Maps


3 min read

Wax is a set of tools aimed to make it easier to put custom maps onto the web with interactivity and other useful UI elements. Since the maps that TileMill creates and TileStream serves are a standard web tile format, it’s possible to use them with practically any web mapping API — Google Maps, Modest Maps, OpenLayers, and so on. Wax includes ‘connectors’ for Modest Maps and Google Maps that make the addition of MapBox-created layers much easier. But even more than that, Wax is what enables maps in all of these APIs to be interactive and to include legends from the tilesets themselves.

Wax is what powers the new version of TileStream that we will be launching later this month. By switching from OpenLayers to Modest Maps and Wax, we are able to reduce file size tremendously — in many cases more than 70%.

3eb1831a5f8c  05Q vuXlxSzYHg5N1

The Wax Manual: http://mapbox.github.com/wax/manual/index.html

This small file size is due to Modest Maps’ extremely minimal framework and that it requires very little legacy code, and Wax was rewritten to use no dependencies — it doesn’t require jQuery or any external framework to run. That said, it includes a static version of reqwest, which is a great replacement for the AJAX library in jQuery.

It’s simple to add interaction to a map using these tools:


But there’s a lot more to be done with the library. It’s what we use on projects, so there are many places where you can add deep customization to make maps behave and look completely differently — custom to any use case. For even more complex use cases, Wax contains the concept of records — ways to store and serve map configurations as data. For configuring hundreds of maps, records can cut down on the level of hacks and templating significantly.

You also get tools to bridge the gap between the extremely minimal Modest Maps API and map controls like those that users have come to expect with Google Maps and OpenLayers. Wax provides good looking zoom controls for a start — and for your app, you can tweak the style thoroughly with CSS. It also adds the familiar zoombox control originated by Schuyler Erle in OpenLayers. We expect to add more to Wax as we move along and possibly create companion libraries that push other aspects of map interaction. We’re also planning to add Leaflet support soon to keep pushing fast, lightweight map integration on the web.

For mobile applications, there’s a ‘Mobile’ control in the toolkit that is designed for a quick plug-and-play mobile experience with existing maps. When an Android or iOS-based mobile browser encounters a page with a map with the mobile control, the map is shown with a play button. Upon tapping the map, it takes over the page with a multi-touch capable (on iOS) display, until you minimize the control and return to the page. It also supports interactive tilesets while in multi-touch mode so our interactive maps can work across desktop browsers, mobile browsers, and native apps.

We’ve written the Wax Manual, which ideally is not just one tool’s manual, but a gentle introduction to how web maps actually work, so that users can become tinkerers. The embedding features of TileStream Pro use Wax internally, so there’s a good chance that you’re using these tools already.

Wax is BSD-licensed open source hosted on GitHub. Check out the manual to get started with Wax or with understanding web mapping in general.

What we're doing.