deCarta API Tutorials
deCarta mapping tutorials for developers of location enabled mobile and web applications. These HTML5 tutorials are a first in a continuous series provided by deCarta.
Getting Started with deCarta Mobile JavaScript API
Introduction
With the introduction of smartphones and advanced mobile browsers, it has become possible to create complex web applications dedicated to the mobile web.
In this series, we'll be building a mobile web mapping application which will allow us to explore the capabilities of modern mobile browsers and learn some techniques to optimize their performance.
As a first step we'll set up a basic application, which will be the base we'll be using throughout the whole series.
Knowledge of JavaScript, HTML, CSS and basic DOM APIs is required.
You'll also need the deCarta Mobile JS API, which can be obtained here.
Unzip the package, and extract the js/deCartaMob.min.js library to a folder of your choice. In the same folder create an empty index.html file. This is the file we'll work on in this first article.
Before we get started.
A few important issues about mobile web development we need to be aware of:
- Limited bandwidth, and possibly high data transfer costs for the user.
- Limited browser caching ability. [http://www.yuiblog.com/blog/2010/06/28/mobile-browser-cache-limits/]
- Wide range of devices with different resolutions and capabilities.
While implementing the application, we should always keep these issues in mind, and try to choose an architecture that will let us minimize the impact on the user.
Our Basic Application
Doctype
In our application, we will be using several
<!doctype html>
Head
There are a few meta tags which are important in the mobile web world, so let's take a quick look.
The Viewport Meta Tag.
This tag has several important roles. It can be used to define the width and height of our document, the mapping of css pixels to physical pixels, and to determine what kind of pinch zoom interaction our app will allow the user to perform.
In typical web spirit, depending on the browser the Viewport Meta Tag is almost, but not quite, entirely unlike its specification.
We would like our application to:
- fill the screen completely, but not exceed it. (no scrolling around the page)
- be displayed at the best possible resolution.
- not allow the user to zoom the page by pinching.
To fill the screen completely and avoid scrolling, we can set:
<meta name="viewport" content="width=device-width; height=device-height;">
this will make the viewport exactly the size of the device's screen.
To ensure that elements are displayed at approximately the same physical size across devices with varying screen resolutions, mobile web browsers introduced the concept of CSS pixels. This is a virtual size metric, which maps to physical pixels at a ratio that keeps elements' size consistent across devices. For example, both the
The deCarta API will detect the correct physical resolution and resize map images and tiles appropriately so that they are always displayed at full resolution.
We can also control how a scaling gesture (a "pinch") will be interpreted by adding:
<meta name="viewport" content="width=device-width; height=device-height;initial-scale=1.0;
maximum-scale=1.0; minimum-scale=1.0; user-scalable=0;">
this is telling the browser that we would rather not let the user zoom in and out as they please. This is probably very inappropriate for a regular website, as the user might want to zoom in to be able to better read the text. However with a map, where zooming is an essential part of the application, we'd like to be in control of that. Most browsers will respect our wishes, with the notable exception of the HTC Android browser, which does not. At the time of writing, this is still an unresolved issue.
iPhone specific meta tags
There are a few iPhone specific meta tags which will define how the phone handles web pages that are added to the phone's home screen.
<!-- Eliminate url and button bars if added to home screen -->
<meta name="apple-mobile-web-app-capable" content="yes" />
<!-- Choose how to handle the phone status bar -->
<meta names="apple-mobile-web-app-status-bar-style" content="black-translucent" />
Styles
It is very important in mobile web applications to minimize the number of http requests.
Typically apps try to bundle all resources required for startup
in a single HTML file, including stylesheets and scripts, which will then be served in a single request.
To minimize transfer time, we should also make sure our web server is configured to serve gzipped content.
This can be accomplished in many different ways: using a build tool, dynamically using tools such as Google's mod_pagespeed, manually while blindfolded and juggling chainsaws...
For the time being, we will inline our very simple stylesheets in the document's head.
<style type="text/css">
* {
margin: 0;
padding: 0;
}
#mapContainer{
overflow:hidden
position: absolute;
top: 0;
left: 0;
}
</style>
Body
Now we can start laying out the HTML structure for our application. Since all we are going to do in this first article is display a full screen map, we won't need much: a simple container will be sufficient.
<div id="mapContainer"></div>
Script
Now we can add the necessary javascript for our application. Since we are starting with a simple draggable map, this is quite straightforward.
One important note here is that we are including the deCarta Mobile JS API as an external file.
Ideally in a production deployment we'd probably want to inline this as well (like with our CSS) to avoid making extra requests.
<script type="text/javascript">
//Add the deCarta credentials
deCarta.Mobile.Configuration.clientName = '*****';
deCarta.Mobile.Configuration.clientPassword = '*****';
deCarta.Mobile.Configuration.configuration = '*****'; // Specify your Navteq data set
//Register a function that will be executed once the document has completed loading.
window.onload = function(){
//Get the size of the window we are working with.
var size = deCarta.Window.getViewport();
//Resize body and map element to perfectly fit the window.
document.body.style.width = size.width + 'px';
document.body.style.height = size.height + 'px';
document.getElementById('mapContainer').style.width = size.width + 'px';
document.getElementById('mapContainer').style.height = size.height + 'px';
//Now instantiate a map!
new deCarta.Mobile.Map({id: "mapContainer"});
}
</script>
Let's quickly go over this simple script. First of all, we need to include our deCarta API keys. Refer to the deCarta devZone for more information. In the onLoad handler, we resize the body and map elements to full screen. We use deCarta.Window.getViewport to get information regarding the window size. This is an abstraction layer which works across devices, giving us consistent information. Lastly, we instantiate a (very) basic map.
Finally...
Make sure everything works by loading the file in a modern desktop browser, such as Firefox, Chrome or Safari. [Try not to use IE6]. If it does, upload to a web server and try it out on your smartphone!
Thanks for reading this article.
Code
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name = "viewport" content = "width=device-width; height=device-height;
initial-scale=1.0; maximum-scale=1.0; minimum-scale=1.0;user-scalable=0;" />
<!-- Eliminate url and button bars if added to home screen -->
<meta name="apple-mobile-web-app-capable" content="yes" />
<!-- Choose how to handle the phone status bar -->
<meta name= "apple-mobile-web-app-status-bar-style" content="black-translucent" />
title>Simple Mobile Map</title>
<style>
* {
margin: 0;
padding: 0;
}
#mapContainer{
overflow:hidden
position: absolute;
top: 0;
left: 0;
}
</style>
</head>
<body>
<div id="mapContainer"></div>
<script type=src="deCartaMob.min.js"></script>
<script type="text/javascript">
deCarta.Mobile.Configuration.clientName = 'MYCLIENTNAME';
deCarta.Mobile.Configuration.clientPassword = 'MYPASSWORD';
deCarta.Mobile.Configuration.configuration = '*****'; // Specify your Navteq data set
window.onload = function(){
var size = deCarta.Window.getViewport();
document.body.style.width = size.width + 'px';
document.body.style.height = size.height + 'px';
document.getElementById('mapContainer').style.width = size.width + 'px';
document.getElementById('mapContainer').style.height = size.height + 'px';
new deCarta.Mobile.Map({id: "mapContainer"});
}
</script>
</body>
</html>
Back to top