Documentation

Custom Fonts

Using a custom font, or a "web font", can add character to a map.

Because the Javascript API makes use of HTML CANVAS, custom fonts need to be fully loaded before the map is drawn. Otherwise, there is a risk of portions of the map being drawn with a backup font while the custom font is still loading. To solve this problem, see 'Base64 Encoding a Font' below.

Cross-Browser Font Compatability

Another concern when using a custom font is having the appropriate formats to be supported in all browsers. Luckily there are plenty of online tools to help designers convert fonts and generate the appropriate CSS syntax to point browsers to the right files.

CSS should follow the 'Bulletproof Syntax' for @font-face declarations, explained here by Paul Irish. In short, each font will need to be declared like this:

@font-face {
    font-family: 'spicy_rice';
    src: url('fonts/spicyrice-regular.eot?#iefix') format('embedded-opentype'),
         url('fonts/spicyrice-regular.woff') format('woff'),
         url('fonts/spicyrice-regular.ttf') format('truetype'),
         url('fonts/spicyrice-regular.svg') format('svg');
    font-weight: normal;
    font-style: normal;
}

Thankfully, a great resource is available for converting fonts into multiple formats and generating the necessary CSS.

Fontsquirrel

Fontsquirrel is an invaluable resource for creating webfont 'kits'. Uploading a font file in one format is all it takes to get a full cross-browser kit of fonts and the CSS to use them. The site is also a great place to browse a variety of free web fonts. Credit goes to Ethan Dunham.

Base64 Encoding a font

One way to ensure a font has loaded and satisfy all cross-browser issues is to base64 encode a font and embed it directly in the CSS file using a data URI. This can be done with Fontsquirrel ( under the 'Expert' mode ), by using another great online tool, Base64Fonts, or doing it yourself. Here is an example of the font 'Acme', the encoded portion has been truncated for brevity.

@font-face {
    font-family: 'acme';
    src: url(data:application/x-font-woff;charset=utf-8;base64,d09GRgA...Ln5WAAA=) format('woff');
    font-weight: normal;
    font-style: normal;
}

The reason this works is because the font is loaded with the CSS rather than via a separate request. This way it must finish loading before the map is drawn and the font will be available in time.

Encoding a font increases its size by about %30, so this solution should only be used for one or two fonts. The increase in size in this case is outweighed by eliminating the need for an additional http request to get the font file. Test your application thoroughly to see the effect on performance.

The Micello Font Kit

A collection of encoded fonts has already been created for our developer's convenience. It can be downloaded here: Micello Font Kit

Setting the Map Font

Once the font files have been loaded with CSS, assign mapCanvas.MAP_FONT the name of the font from the @font-face declaration:

function mapInit() {
    mapControl = new micello.maps.MapControl('mapElement');
    mapCanvas = mapControl.getMapCanvas(); // get the mapGUI object
    mapCanvas.MAP_FONT = "acme"; // specify font(s)
    mapData = mapControl.getMapData();
    mapData.loadCommunity(15);   
}