×
Namespaces

Variants
Actions
Revision as of 18:59, 24 April 2013 by jasfox (Talk | contribs)

HERE Maps API - Asynchronous Loading

From Nokia Developer Wiki
Jump to: navigation, search

This article explains how to load the HERE Maps JavaScript API asynchronously.

Article Metadata
Tested with
Devices(s): Internet Explorer, Google Chrome , Firefox
Dependencies: HERE Maps API for JavaScript v 2.2.4 or higher
Article
Keywords: HERE Maps, asynchronous, JavaScript, Features
Created: jasfox (27 Feb 2013)
Last edited: jasfox (24 Apr 2013)

Contents

Introduction

Since the release of version 2.2.4 of the HERE Maps API for JavaScript, the API library has been able to support asynchronous loading. Asynchronous loading is a means of "bootstrapping" the API, so that, instead of there being a static JavaScript declaration in the header of the HTML, the API can be loaded via calling a script which itself is injected into the DOM.

Synchronous Map Loading

Basic synchronous loading of the API requires the following declaration in the <header> of the file:

<script type="text/javascript"
src="http://api.maps.nokia.com/2.2.4/jsl.js" charset="utf-8">
</script>

A <div id="mapContainer"/> follows further down the page, and the map can be initialized with a further JavaScript function as shown (substituting in the appropriate App Id and token )

/////////////////////////////////////////////////////////////////////////////////////
// Don't forget to set your API credentials
//
// Replace with your appId and token which you can obtain when you
// register on http://api.developer.nokia.com/
//
nokia.Settings.set( "appId", "YOUR APP ID");
nokia.Settings.set( "authenticationToken", "YOUR TOKEN");
//
/////////////////////////////////////////////////////////////////////////////////////
 
var mapContainer = document.getElementById("mapContainer");
var map = new nokia.maps.map.Display(mapContainer, {
center : [ 40.67, -73.94 ],
zoomLevel : 13,
components : [ new nokia.maps.map.component.ZoomBar(),
new nokia.maps.map.component.Behavior(), ]
});

Asynchronous Map Loading

Asynchronous map loading attempts to do the same thing, except that the static <script> declaration is removed from the header, and injected dynamically into the DOM using JavaScript.

DOM injection of a <script>

Creating a <script> and injecting it into the <header>, is a relatively simple procedure, and just involves using the DOM manipulation methods document.createElement() and appendChild()

var oScript = document.createElement("script")
oScript.type = "text/javascript";
oScript.src = "http://api.maps.nokia.com/2.2.4/jsl.js?blank=true";
document.getElementsByTagName("head")[0].appendChild(oScript);

Note that the library requires the additional parameter blank=true, to avoid loading any further Features.

Adding a callback once the <script> has been loaded

The previous step will merely add the <script> into the <header>, for further processing a callback will be required to continue

 oScript.onload = onScriptLoad;

Where onScriptLoad() is a new function (shown below). As mentioned previously, no Features, not even the basic map Features have been loaded by the API yet, so the function onScriptLoad() must be used to load the desired Features, using the Feature loader

 var onScriptLoad = function() {
nokia.Features.load(
nokia.Features.getFeaturesFromMatrix(["all"]),
onApiFeaturesLoaded,
onApiFeaturesError,
null,
false
);

The nokia.Features.load(), takes the following parameters:

  • The Features as an array of key-value pairs - the short-cut nokia.Features.getFeaturesFromMatrix(["all"]) will load all available Features.
  • A callback method for further processing once the requested Features have been loaded
  • A callback method for further processing should the requested Features fail to load
  • A target document - this should be set to null if the current document is to be used
  • A flag indicating whether the Feature loading itself is synchronous or asynchronous.

Further processing once the Features have been loaded

The onApiFeaturesLoaded() function continues processing by setting the App Id and token, and displaying the map, as can be seen, it matches the code from the synchronous example above.

var onApiFeaturesLoaded = function() {
 
/////////////////////////////////////////////////////////////////////////////////////
// Don't forget to set your API credentials
//
// Replace with your appId and token which you can obtain when you
// register on http://api.developer.nokia.com/
//
nokia.Settings.set( "appId", "YOUR APP ID");
nokia.Settings.set( "authenticationToken", "YOUR TOKEN");
//
/////////////////////////////////////////////////////////////////////////////////////
 
var mapContainer = document.getElementById("mapContainer");
var map = new nokia.maps.map.Display(mapContainer, {
center : [ 40.67, -73.94 ],
zoomLevel : 13,
components : [ new nokia.maps.map.component.ZoomBar(),
new nokia.maps.map.component.Behavior(), ]
});
};

Error processing if the Features cannot be loaded

Should an error occur, the onApiFeaturesError() function will display the error text associated with the error, which can be useful for debugging purposes.

var  onApiFeaturesError = function(error) {
alert("Whoops, an error occurred. " + error);
};


Working Example of Asynchronous Map Loading

The following fully working example will asynchronously load and display a map of New York.

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<title>Asynchronous Loading</title>
<style type="text/css">
/* <![CDATA[ */
body {
margin: 0;
padding: 0;
}
 
#mapContainer {
width: 100%;
height: 100%;
position: absolute;
overflow: hidden;
top: 0;
left: 0;
}
/* ]]> */
</style>
</head>
<body>
<div id="mapContainer"></div>
 
<script type="text/javascript">
/* <![CDATA[ */
// this is our initial script that will load jsl.js
var oScript = document.createElement("script"),
//once the jsl.js is load, we load all features
onScriptLoad = function() {
nokia.Features.load(
nokia.Features.getFeaturesFromMatrix(["all"]),
onApiFeaturesLoaded, // an callback when everything was successfully loaded
onApiFeaturesError, // an error callback
null, // Indicates that the current document applies
false //Indicates that loading should be asynchronous
);
},
// once all features we loaded, we can instantiate the map
onApiFeaturesLoaded = function() {
 
/////////////////////////////////////////////////////////////////////////////////////
// Don't forget to set your API credentials
//
// Replace with your appId and token which you can obtain when you
// register on http://api.developer.nokia.com/
//
nokia.Settings.set( "appId", "YOUR APP ID");
nokia.Settings.set( "authenticationToken", "YOUR TOKEN");
//
/////////////////////////////////////////////////////////////////////////////////////
 
var mapContainer = document.getElementById("mapContainer");
var map = new nokia.maps.map.Display(mapContainer, {
center : [ 40.67, -73.94 ],
zoomLevel : 13,
components : [ new nokia.maps.map.component.ZoomBar(),
new nokia.maps.map.component.Behavior(), ]
});
},
// if an error occurs during the feature loading
onApiFeaturesError = function(error) {
alert("Whoops! " + error);
};
 
oScript.type = "text/javascript";
// NOTE: tell jsl.js not to load anything by itself by setting "blank=true"
oScript.src = "http://api.maps.nokia.com/2.2.4/jsl.js?blank=true";
// assign the onload handler
oScript.onload = onScriptLoad;
 
//finally append the script
document.getElementsByTagName("head")[0].appendChild(oScript);
/* ]]> */
</script>
</body>
</html>
213 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×