nokia.mh5.components.Map

Class Summary

This is a component providing map functionality.

[ For full details, see nokia.mh5.components.Map ]

Table 1. Property Summary
Properties

{Boolean} addressLookup

Enables long press on map and click on the position marker to show the info bubble with the address of the place.

{Array} box

The current map bounding box which defines the bounderies of the visible map area.

{Object} center

The current map center.

{Object} infoBubbleParams

Configuration object for the infoBubble

{Array} infoBubbles

infoBubbles shown on the map nokia.mh5.components.InfoBubble.

{Boolean} isReady

Set to true after firing "ready" event.

{nokia.mh5.ui.Control} mapLogo

The nokia logo shown on the map.

{Object} offset

The current map offset, accordingly with the top, left corner of the current page.

{Boolean} passive

Setting to disable all the map controls, cartoPois, positioning and events.

{Array} pois

This is an experimental property which should make creation of pois easier.

{Object} position

This property can be used to retrieve the current latitude and longitude.

{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.

{Object} schema

Specific schema of the map.

{nokia.mh5.ui.Button} settingsButton

Button which opens the map settings dialog.

{Object} size

The current map canvas size.

{Object} zoom

The current zoom level.

Table 2. Method Summary
Methods

addLayer (callback, layerId)

Add a layer callback, if not present already, on top of the basic map.

addPoi (_pois)

Adds a POI object to the map.

covers (points) : {Boolean}

Does the current map view cover a set of points

createPoi (icon, coords) : {Object}

Creates poi object and shows it on the map.

geoToPoint (coords) : {Object}

Converts a generic coordinates object into an map point.

getPois (place, firstOnly) : {Object | Array}

Returns a poi(s) which match(es) the specified data (id or longitude/latitude pair).

hasLayer (aLayer) : {Boolean}

Check whether layer is displayed on the map

hideInfoBubble (infoBubbles)

Hides the specified infobubble, if it's shown.

initPositioning ()

Triggers initialization of positioning.

move (diffX, diffY)

Moves the map directly to the new point.

moveTo (coord)

Moves the map directly to the new point.

onPositionStatusChange (positionStatus)

Handler which will be called if the position status has changed.

passiveDidChange (passive)

Bound to the passive property.

pointToGeo (point) : {Object}

Converts a map point into an coordinates.

removeLayer (aLayer)

Remove a layer by callback or id, if present already, from the top of the basic map.

removePoi (_pois)

Removes one or more poi objects from the map.

removeStoredTiles ()

Removes previously stored tiles.

resize ()

Resizes the map instance, so it takes the size of it's container.

restore ()

Try to restore an already saved map state.

save ()

Saves the current map state using either W3C localStorage, where available, or cookies.

showInfoBubble (poi, params)

Shows an infoBubble.

showStoredTiles (callback, errback)

Shows currently saved tiles asynchronoulsy (if any) by moving map to the last stored bounding box.

storeTiles (params) : {Object}

Stores tiles for given bounding box in SQL Storage.

Class Description

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.

Note that the properties of this class include (in addition to the properties listed directly as class members):

Constructor Details

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

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.

Parameters:
 
props

type: {Object}

properties for the Map
props.infoBubble

type: {Object}

infobubble properties nokia.mh5.components.InfoBubble.
props.listeners

type: {Object}

listeners for map events.
props.listeners.poiclick

type: {Function}

called when a poi is clicked. As parameter you get the clicked poi.
props.listeners.mapmovestart

type: {Function}

called when the user starts to move the map
props.listeners.mapmoveend

type: {Function}

called when the user ends to move the map
props.listeners.mapclick

type: {Function}

called when the user clicks on the map. As parameter you get longitude and latitude of the clicked location
props.listeners.mapdblclick

type: {Function}

called when the user double clicks on the map
props.listeners.maplongpress

type: {Function}

called when the user long presses on the map. As parameter you get longitude and latitude of the selected location
props.listeners.maptrackingstart

type: {Function}

called when the user starts to track the map
props.listeners.maptrackingend

type: {Function}

called when the user ends to track the map
props.listeners.mapzoomchange

type: {Function}

called when the zoom level changes. As parameters you get the
props.listeners.ready

type: {Function}

called when the map is initialized and is ready to use
props.appId

type: {String}

[optional]  your application id. Deprecated - use nokia.mh5.appId instead.
props.appCode

type: {String}

[optional]  your application code. Deprecated - use nokia.mh5.appCode instead.
parentContainer

type: {nokia.mh5.ui.Container}

parent of the component

Example:

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

Property Details

{Boolean} addressLookup

Enables long press on map and click on the position marker to show the info bubble with the address of the place.

{Array} box

The current map bounding box which defines the bounderies of the visible map area. The coordinates in the array have to be ordered clockwise. Can be used to get and set the current bounding box.

{Object} center

The current map center. Can be used to get and set the current map center.

{Object} infoBubbleParams

Configuration object for the infoBubble

{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.

Example:

                                var map = new nokia.mh5.components.Map({
  listeners: {
     poiclick: function(e) {
         e.preventDefault();//prevents hiding open infoBubbles and opening a new one
         this.showInfoBubble(e.data[0]);
     },
     mapclick: function(e) {
         e.preventDefault();//prevents hiding open infoBubbles
     },
     maplongpress: function(e) {
         e.preventDefault();//prevents hiding open infoBubbles and opening a new one
     },
  }
});
document.body.appendChild(map.root);
                            

{Boolean} isReady

Set to true after firing "ready" event.

The nokia logo shown on the map.

{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.

{Boolean} passive

Setting to disable all the map controls, cartoPois, positioning and events. The component shows a non interactive map.

{Array} pois

This is an 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.

{Object} position

This property can be used to retrieve the current latitude and longitude.

{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.

{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", "normal.day.community", "hybrid.day.community".

{nokia.mh5.ui.Button} settingsButton

Button which opens the map settings dialog.

{Object} size

The current map canvas size. Can be used to get and set the canvas size.

{Object} zoom

The current zoom level. A number between 3 and 19. Can be used to get and set the zoom.

Method Details

addLayer(callback, layerId)

Add a layer callback, if not present already, on top of the basic map.

Parameters:
 
callback

type: {Function}

a callback that will be called per every tile drawn on Map Arguments received by the layer callback are: tileX {Number} the tile X, not as pixels but as world grid position tileY {Number} the tile Y, not as pixels but as world grid position tiles {Number} the total amount of tiles in the map zoom {Number} the current map zoom level (MIN_ZOOM_LEVEL to MAX_ZOOM_LEVEL) pixels {Number} the size of the whole world in pixels at current zoom level schema {String} the currently used map schema The function may or may not return a string. If it does, this string will be used as tile image src.

layerId

type: {String}

a layer identifier

addPoi(_pois)

Adds a POI object to the map.

Parameters:
 
_pois

type: {Object | Arrray}

poi(s) which was(were) created by nokia.mh5.components.Map.createPoi and then removed by nokia.mh5.components.Map.removePoi from the map.

covers(points) : {Boolean}

Does the current map view cover a set of points

Parameters:
 
points

type: {Array}

points to test

points.point

type: {Object}

a point from the array points

points.point.latitude

type: {Number}

requred

points.point.longitude

type: {Number}

requred

Returns:
{Boolean} returns true if the current viewport covers the points.

createPoi(icon, coords) : {Object}

Creates poi object and shows it on the map.

Parameters:
 
icon

type: {String}

the associated image src, absolute or relative path

coords

type: {Object}

coordinates object

coords.longitude

type: {Number}

longitude

coords.latitude

type: {Number}

latitude

Returns:
{Object} created poi object, which can be used as parameter for nokia.mh5.components.Map.removePoi and nokia.mh5.components.Map.addPoi

geoToPoint(coords) : {Object}

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.

Parameters:
 
coords

type: {Object}

object with longitude and latitude to convert

coords.longitude

type: {Number}

longitude of the coordinates

coords.latitude

type: {Number}

latitude of the cooordinates

Returns:
{Object} the object with x and y properties describing a point on the map

getPois(place, firstOnly) : {Object | Array}

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.

Parameters:
 
place

type: {Object}

[optional] 

object specifying id or longitude/latitude of the poi to return

place.placeId

type: {String}

[optional] 

place id

place.longitude

type: {Number}

[optional] 

longitude

place.latitude

type: {Number}

[optional] 

latitude

firstOnly

type: {Boolean}

[optional] 

when it's true returns the first found poi

Returns:
{Object | Array} poi(s) which matche(s) the specified data (id or longitude/latitude pair) or an array containing all pois if the parameter isn't specified. If the place to find has an id an object will be return. If comparison is based on longitude/latitude an array will be returned.

hasLayer(aLayer) : {Boolean}

Check whether layer is displayed on the map

Parameters:
 
aLayer

type: {Function | String}

a callback or id of layer to be checked

Returns:
{Boolean} true if layer with given callback or id exists, otherwise false

hideInfoBubble(infoBubbles)

Hides the specified infobubble, if it's shown. If the infobubble poi has "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.

Parameters:
 
infoBubbles

type: {Object | Array}

an infoBubble or an array with infoBubbles to close. If this parameter is not defined, then all shown infoBubbles will be closed.

initPositioning()

Triggers initialization of positioning.

See:
nokia.mh5.components.Map.onPositionStatusChange

move(diffX, diffY)

Moves the map directly to the new point.

Parameters:
 
diffX

type: {Number}

the difference in pixels from the current map center on the x axis

diffY

type: {Number}

the difference in pixels from the current map center on the y axis

moveTo(coord)

Moves the map directly to the new point.

Parameters:
 
coord

type: {Object}

object containing longitude and latitude to move the map to

coord.longitude

type: {Number}

longitude.

coord.latitude

type: {Number}

latitude.

onPositionStatusChange(positionStatus)

Handler which will be called if the position status has changed.

Parameters:
 
positionStatus

type: {String}

new position status. The possible values are: "uninitialized", "available", "requesting", "unavailable", "denied".

passiveDidChange(passive)

Bound to the passive property. updates the interactivity of the map and the visibility of various components

Parameters:
 
passive

type: {String}

The new value of the passive property

pointToGeo(point) : {Object}

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.

Parameters:
 
point

type: {Object}

the object with x and y properties describing a point on the map

Returns:
{Object} object with longitude and latitude

removeLayer(aLayer)

Remove a layer by callback or id, if present already, from the top of the basic map.

Parameters:
 
aLayer

type: {Function | String}

a callback or id of layer that will be removed and never notified again per each tile.

removePoi(_pois)

Removes one or more poi objects from the map.

Parameters:
 
_pois

type: {Object | Array}

[optional] 

poi or an array of pois to remove. If no poi is defined, all pois on the map will be removed

removeStoredTiles()

Removes previously stored tiles.

resize()

Resizes the map instance, so it takes the size of it's container.

restore()

Try to restore an already saved map state. If nokia.mh5.components.Map.save has never been called, restore will do nothing.

save()

Saves the current map state using either W3C localStorage, where available, or cookies.

See:
nokia.mh5.components.Map.restore

showInfoBubble(poi, params)

Shows an infoBubble. InfoBubble replaces POI. The original POI image will be saved in the "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.

Parameters:
 
poi

type: {Object}

the POI to show the infoBubble for. If there is no poi, the poi will be created. In this case after the infoBubble is closed no POI will be left.

params

type: {Object}

[optional] 

parameters for infoBubble configuration nokia.mh5.components.InfoBubble

params.renderOnly

type: {Boolean}

[optional] 

false by default, set to true to prevent map from moving if infoBubble doesn't fit in current viewport

showStoredTiles(callback, errback)

Shows currently saved tiles asynchronoulsy (if any) by moving map to the last stored bounding box.

Parameters:
 
callback

type: {Function}

[optional] 

Function called after successfully loading stored tiles

errback

type: {Function}

[optional] 

Function called if error occurs while loading offline tiles

storeTiles(params) : {Object}

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.

Parameters:
 
params

type: {Object}

[optional] 

Parameters for storing tiles in SQL Storage

params.box

type: {Object}

[optional] 

Bounding box of area to store

params.callback

type: {Function}

[optional] 

Function that will be called during saving with event object that contains type of event: "progress", "load", "error"; message for current event type and data property with with total and current amount of downloaded data

params.hold

type: {Boolean}

[optional] 

By default, storing tiles starts automatically, to delay it, this parameter has to be set to true

Returns:
{Object} Object to control saving process which contains stop and resume functions, as well as onprogress property which can be used to assign progress callback or undefined if storage is unavailable