MapClass

This is a component providing map functionality. It consists of a map instance and the following controls: zoom (only on android and desktop. On iOS the zoom control is hidden due to pinch), position and map settings buttons. The class offers tracking of the user position, which can be activated by clicking on the position button or setting nokia.mh5.components.Map.tracking to true. The component shows POIs on the map. You can define the shown icons. If the user clicks on one of the shown places, the Map opens a default info bubble with the name of the place. After a long press on the map an info bubble opens showing the address of the location. At it's simplest:

Example

 var map = new nokia.mh5.components.Map({});
 document.body.appendChild(map.root);      

Or, a more complex example, with many parameters being set:

Example

 var map = new nokia.mh5.components.Map({
   schema: "normal.day.traffic",
   center: {
     longitude: 52,
     latitude: 13
   },
   zoom: 15,
   listeners: {
      poiclick: function(e) {},
      mapmovestart: function(e) {},
      mapmoveend: function(e) {},
      mapclick: function(e) {},
      mapdblclick: function(e) {},
      maplongpress: function(e) {},
      maptrackingstart: function(e) {},
      maptrackingend: function(e) {},
      mapzoomchange: function(e) {}
   }
 });
 document.body.appendChild(map.root);
 var poi = map.createPoi("myIcon.png", {longitude: 53, latitude: 14});
 map.moveTo(poi);
 map.showInfoBubble(poi, params);      

Inheritance hierarchy

nokia.mh5.Class
  nokia.mh5.ui.Control
    nokia.mh5.ui.Container
        nokia.mh5.components.Map

Constructor Detail

Creates a map component. The map instance is created immediately, but its initialization is triggered later after the map container node is in the dom.

new nokia.mh5.components.Map(props, parentContainer);

Constructor Parameters

Type Name Description
Object props properties for the Map
nokia.mh5.ui.Container parentContainer parent of the component
Object props.infoBubble infobubble properties nokia.mh5.components.InfoBubble.
Object props.listeners listeners for map events.
Function props.listeners.poiclick called when a poi is clicked. As parameter you get the clicked poi.
Function props.listeners.mapmovestart called when the user starts to move the map
Function props.listeners.mapmoveend called when the user ends to move the map
Function props.listeners.mapclick called when the user clicks on the map. As parameter you get longitude and latitude of the clicked location
Function props.listeners.mapdblclick called when the user double clicks on the map
Function props.listeners.maplongpress called when the user long presses on the map. As parameter you get longitude and latitude of the selected location
Function props.listeners.maptrackingstart called when the user starts to track the map
Function props.listeners.maptrackingend called when the user ends to track the map
Function props.listeners.mapzoomchange called when the zoom level changes. As parameters you get the
Function props.listeners.ready called when the map is initialized and is ready to use
String [props.appId] your application id. Deprecated - use nokia.mh5.appId instead.
String [props.appCode] your application code. Deprecated - use nokia.mh5.appCode instead.

Methods    Hide Inherited

public covers(points) Does the current map view cover a set of points
publicinherited getContentRoot() Returns the real DOM node of the control without scroll wrapper (if present).
public createPoi(icon, coords) Creates poi object and shows it on the map.
public addPoi(_pois) Adds poi object to the map.
publicinherited add(control, name) Adds a control with the specified name to the container and adds the "parent" property set to the container to it.
publicinherited build() Calls the build functions of all children (if available). In here children can already access the tree of UI controls, which isn't possible in the constructor.
public geoToPoint(coords) Converts a generic coordinates object into an map point. Please note, convertion is based on the current zoom level, which means that same coordinates will produce different results if we change the nokia.mh5.components.Map.zoom.
public addLayer(callback, layerId) Add a layer callback, if not present already, on top of the basic map.
public save() Saves the current map state using either W3C localStorage, where available, or cookies.
public hasLayer(aLayer) Check whether layer is displayed on the map
public getPois(place, firstOnly) Returns a poi(s) which match(es) the specified data (id or longitude/latitude pair). If no data is specified all pois will be returned.
publicinherited getRootOwnerByClass(Class) Retrieves the instance that owns the root node of the specified Class. Used to retrieve creator of the component inside bound events.
public initPositioning(origin) Triggers initialization of positioning.
public hideInfoBubble(infoBubbles) Hides the specified infobubble, if it's shown. If the infobubble poi has "data.originalImage" property, which points to the original image of the poi, it will be restored. If the "originalImage" property isn't found (e.g. reverse geocoding), the poi will be just removed from the map. If the parameter infoBubbles is not defined all visible infoBubbles will be hidden. The removed infoBubble(s) will be removed from nokia.mh5.components.Map.infoBubbles array.
publicinherited prepareBindings() Calls prepareBindings on children controls (if available) and itself.
public onPositionStatusChange(positionStatus) Handler which will be called if the position status has changed.
public move(diffX, diffY) Moves the map directly to the new point.
publicinherited insertBefore(control, name, referenceControlName) Inserts a control with a specified name to the container before the control with the specified name and adds the "parent" property set to the container to it.
public moveTo(coord) Moves the map directly to the new point.
public showInfoBubble(poi, params) Shows an infoBubble. InfoBubble replaces POI. The original POI image will be saved in the "data.originalImage" property of the POI and restored after the infoBubble will be closed. The created infoBubble will be added to nokia.mh5.components.Map.infoBubbles array. The passed POI object gets a property "infoBubble" equal true that will be removed after the infoBubble is hidden. The created infoBubble will include "poi" property which contains the POI itself, additionaly to its own properties.
public removeLayer(aLayer) Remove a layer by callback or id, if present already, from the top of the basic map.
public passiveDidChange(passive) bound to the passive property. updates the interactivity of the map and the visibility of various components
publicinherited prepareDidChangeNotifications() Calls prepareDidChangeNotifications on children controls (if available) and itself.
public pointToGeo(point) Converts a map point into an coordinates. Please note, convertion is based on the current zoom level, which means that a point retrieved with zoom level 19 will result into a different coordinates if the zoom is 18 or less.
publicinherited remove(name) Removes a specified a control from the container, if it can be found.
public removePoi(_pois) Removes one or more poi objects from the map.
public removeStoredTiles() Removes previously stored tiles.
public resize() Resizes the map instance, so it takes the size of it's container.
public restore() Try to restore an already saved map state. If nokia.mh5.components.Map.save has never been called, restore will do nothing.
public showStoredTiles(callback, errback) Shows currently saved tiles asynchronoulsy (if any) by moving map to the last stored bounding box.
public storeTiles(params) Stores tiles for given bounding box in SQL Storage. If there is enough space in the storage the function will save more than only one zoom level of the specified area. Currently you can save only one map area. That means every further call of the function will remove the previously stored tiles.

Properties

public Array infoBubbles infoBubbles shown on the map nokia.mh5.components.InfoBubble. You can think of an infoBubble as an extended presentation of a poi. The default internal behavior of Map component is to show only one infoBubble at the same time. That means it closes the previous infoBubble before showing a new one. If you open an infoBubble on your own by calling nokia.mh5.components.Map.showInfoBubble it's your responsibility to close the existing infoBubble. But you can have multiple infoBubbbles at the same time. For this you have to overwrite some listeners to prevent the default behavior. Please take a look how to do it at the following example.
public Object box the current map bounding box. Can be used to get and set the current bounding box.
public Object center the current map center. Can be used to get and set the current map center.
public Boolean addressLookup Enables long press on map and click on the position marker to show the info bubble with the address of the place.
public Object position position property can be used to retrieve the current latitude and longitude
public nokia.mh5.ui.Button settingsButton button, which opens the map settings dialog
public Object infoBubbleParams configuration object for the infoBubble
public nokia.mh5.ui.Button positionButton button, which the user can use to move the map to their position, if the position is localized, and to start the tracking of the user position. If the user position is localized, the button gets green color, if the position is unknown, it's grey.
public Object schema specific schema of the map. Can be used to get and set the current schema of the map. Possible values are "normal.day", "hybrid.day", "normal.day.transit", "normal.day.traffic"
public Array pois It's experimental property which should make creation of pois easier. If you update this property with an array of poi data the map will call createPoi for every element in the array. You can specify the icon of every poi via "mapIcon" if this icon is specific for map only. If the "mapIcon" property is missing nokia.mh5.utils.place.getCategoryIcon will be used to get the right icon for the poi.
public nokia.mh5.ui.Control mapLogo the nokia logo shown on the map
public Object offset the current map offset, accordingly with the top, left corner of the current page. Can be used to get and set the current map offset.
public Boolean passive setting to disable all the map controls, cartoPois, positioning and events. The component shows a non interactive map.
public Object route object describing the route points. It could be an array with latitude, longitude of every point of your route or an array with objects representing every point of your route
public Object shape object describing the polygon points. It can be an array with latitude, longitude of every point of your polygon or an array of objects with color and shape properties
public Object size the current map canvas size. Can be used to get and set the canvas size.
public Object statics Properties of this object will be attached to constructor function as statics
public Boolean tracking enables and disables tracking mode of the map. The map follows the user position. Set this property only if the position is available.
public Object zoom the current zoom level. A number between 3 and 19. Can be used to get and set the zoom.
public nokia.mh5.ui.Container zoomButtons zoom buttons container containing zoom in and zoom out button. It's displayed on devices which don't support pinching

Events

nokia.mh5.components.Map has no events.

Callbacks

nokia.mh5.components.Map has no callbacks.

Classes

nokia.mh5.components.Map has no classes.

Constants

staticpublic Number n.a. MAX_ZOOM_LEVEL Do not allow the map to zoom further in than this (Range: 1-20)
staticpublic Number n.a. MIN_ZOOM_LEVEL Do not allow the map to zoom further out than this (Range: 1-20)

Interfaces

nokia.mh5.components.Map has no interfaces.