×
Namespaces

Variants
Actions
Revision as of 12:48, 28 November 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
Code ExampleTested with
Devices(s): Internet Explorer, Google Chrome , Firefox
Dependencies: HERE Maps API for JavaScript v 2.5.3 or higher
Article
Keywords: HERE Maps, asynchronous, JavaScript, Features
Created: jasfox (27 Feb 2013)
Last edited: jasfox (28 Nov 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://js.api.here.com/se/2.5.3/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("app_id", "YOUR APP ID");
nokia.Settings.set("app_code", "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://js.api.here.com/se/2.5.3/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("app_id", "YOUR APP ID");
nokia.Settings.set("app_code", "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(), ]
});
map.addListener("displayready", function () {
// add a callback to your code here
}, false);
};

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 displays a static map of Europe. It will asynchronously load and display a pannable, zoomable map with a marker when clicked.

http://rawgithub.com/heremaps/examples/master/maps_api_for_javascript/advanced-examples/asynchronous-loading.html

186 page views in the last 30 days.
×