Maps API for JavaScript Developer's Guide

Map Controls and UI

The HERE Maps API for JavaScript provides a set of ready-made map controls through the UI module (mapsjs-ui.js). In addition, the module supports the creation of info bubbles.

The UI allows you to add the following default components to the map:

  • MapSettingsControl – allows the user to change the base map
  • ZoomControl – allows the user to change the map zoom level
  • Scalebar – shows the current map scale
  • Pano – shows a button to enter and leave StreetLevel

Adding UI Components to the Map

The following example demonstrates how to add UI components to the map.

The first step is to add a <script> tag to the <head> element of the page to load the API's UI module and a link to the CSS file as shown in the code below:

<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="initial-scale=1.0, 
      width=device-width" />
    <script src="http://js.api.here.com/v3/3.0/mapsjs-core.js" 
      type="text/javascript" charset="utf-8"></script>
    <script src="http://js.api.here.com/v3/3.0/mapsjs-service.js" 
      type="text/javascript" charset="utf-8"></script>
    <script src="http://js.api.here.com/v3/3.0/mapsjs-ui.js" 
      type="text/javascript" charset="utf-8"></script>
    <link rel="stylesheet" type="text/css" 
      href="http://js.api.here.com/v3/3.0/mapsjs-ui.css" />
  </head>

Next, create a map object with the default map types in the script section for the application logic.

Note: The default UI requires a map instance as well as a collection containing the default map layers.
<script type="text/javascript" charset="utf-8">
  //Initialize the Platform object:
  var platform = new H.service.Platform({
    'app_id': '{YOUR_APP_ID}',
    'app_code': '{YOUR_APP_CODE}'
  });

  // Get the default map types from the Platform object:
  var defaultLayers = platform.createDefaultLayers();

  // Instantiate the map:
  var map = new H.Map(
    document.getElementById('mapContainer'),
    defaultLayers.normal.map,
    {
      zoom: 10,
      center: { lng: 13.4, lat: 52.51 }
    });

  // Create the default UI:
  var ui = H.ui.UI.createDefault(map, defaultLayers);
</script>

In the image below, the resulting map shows the default controls (the scale bar at the bottom, the zoom control on the right, and the map selector in the bottom right corner).

Figure 1. Map with the default controls

Note, that the Pano control does appear in the map user interface shown above. The UI detects whether the StreetLevel module (mapsjs-pano.js) has been loaded and makes the corresponding UI control visible only when the module is available.

The following example shows the default UI when the StreetLevel module is loaded in the containing HTML page.

Figure 2. Map with the default controls (with Pano visible)

When you create the default UI, an instance of each control is added to the UI object. The controls can be enabled or disabled (removed) individually via calls to the method getControl() defined on the H.ui.UI class. To identify the control you wish to manipulate, you must use the appropriate key:

  • 'mapsettings' – identifies the MapSettingsControl
  • 'zoom' – identifies the ZoomControl
  • 'scalebar' – identifies the ScaleBar
  • 'panorama' – identifies Pano (StreetLevel)

The code below shows how to use the method getControl() and a control identifier to disable the zoom control:

ui.getControl('zoom').setEnabled(false)

Changing the UI Language

The UI module comes with localizations for the following languages:

  • en-US – English (United States)
  • de-DE – German
  • es-ES – Spanish
  • fi-FI – Finnish
  • fr-FR – French
  • it-IT – Italian
  • nl-NL – Dutch
  • pl-PL – Polish
  • pt-BR – Portuguese (Brazil)
  • pt-PT – Portuguese (Portugal)
  • ru-RU – Russian
  • tr-TR – Turkish
  • zh-CN – Chinese (China)

The code that follows uses a language identifier to present the map user interface in German.

<script type="text/javascript" charset="utf-8">
  //Initialize the Platform object:
  var platform = new H.service.Platform({
    'app_id': '{YOUR_APP_ID}',
    'app_code': '{YOUR_APP_CODE}'
  });

  // Get the default map types from the Platform object:
  var defaultLayers = platform.createDefaultLayers();

  // Instantiate the map:
  var map = new H.Map(
    document.getElementById('mapContainer'),
    defaultLayers.normal.map,
    {
      zoom: 10,
      center: { lng: 13.4, lat: 52.51 }
    });

  // Create the default UI:
  var ui = H.ui.UI.createDefault(map, defaultLayers, 'de-DE');
</script>

The image below shows the effect of this code as seen by the application user.

Figure 3. All UI controls localized in German

Managing the Position of UI Controls

A further option supported by the Maps API allows you to change the position of the UI controls. In the following example, all map controls are moved to the top-left corner of the map viewport.

The code extends the previous example by obtaining an instance of each of the default UI controls and then setting alignment on the controls to the top-left corner.

var mapSettings = ui.getControl('mapsettings');
var zoom = ui.getControl('zoom');
var scalebar = ui.getControl('scalebar');
var panorama = ui.getControl('panorama');

panorama.setAlignment('top-left');
mapSettings.setAlignment('top-left');
zoom.setAlignment('top-left');
scalebar.setAlignment('top-left');

The image below shows the results of executing this code.

Figure 4. All UI controls aligned top-left

Info Bubbles

In addition to map controls, the UI module supports info bubbles. An info bubble allows you literally to show a 'bubble' containing HTML content on the map, for example text or images.

The code below extends the first example in this article by adding an info bubble to the map display. It creates an instance of InfoBubble, specifying the geographic coordinates of the location at which it should appear, and the HTML content, which in this case is the text string "Hello World!" in bold. The last line adds the info bubble object to the UI instance.

// Create an info bubble object at a specific geographic location:
var bubble = new H.ui.InfoBubble({ lng: 13.4, lat: 52.51 }, {
        content: '<b>Hello World!</b>'
       });

// Add info bubble to the UI:
ui.addBubble(bubble);

The image below shows the results of executing the code.

Figure 5. Opening an info bubble