MapWrapper Reference Guide | NetToolKit Geo Docs

Release NotesMapWrapper Beta-1.0.0

Backwards incompatible changes:

MapWrapper.Map

renamed getBoundary() to getBounds()
renamed setBoundary() to setBounds()
addFeatures() returns an array of Feature objects instead of an array of feature ids
removeFeatures() takes in an array of Feature objects instead of an array of feature ids

MapWrapper.Marker

renamed getPosition() to getLocation()
renamed setPosition() to setLocation()

Miscellaneous

renamed Point class to Location
renamed point field on Event to location
changed the structure of FeatureOptions
removed tileSource option from MapOptions (instead use rasterTileSource option)
renamed MarkerOptions position option to location
removed MapWrapper.TileSource constants
added a MapWrapper CSS file (https://api.nettoolkit.com/geo/mapwrapper-beta-1.0.0.css?key=your_ntk_api_key_here)

Backwards compatible changes:

MapWrapper.Map

added getFeatures()
addFeatures() now accepts GeoJSON with geometry type "GeometryCollection"

MapOptions

added showNetToolKitAttribution option
added attributionPosition option
added vectorTileStyle option
added rasterTileSource option
added customAttribution option

Miscellaneous

added Mapbox GL JS as a provider
added Feature class
added support for MapWrapper.Event.MOUSEOUT for MapWrapper.Marker
added equals() to Location
various bug fixes

Map

Methods

constructor(options, [callback])

Parameters:

optionsMapOptions(required)

callbackfunction(optional)

A function to be called after the map has been initialized. Customizations such as adding markers must be done after the map has been constructed; this callback is called after the map is ready, avoiding potential race conditions.

addEventListener(eventName, listener)

Parameters:

eventNameMapWrapper.Event(required)

name of the event to listen to

listenerfunction(required)

The function to be invoked when the event is triggered. The function will receive an Eventobject as an argument.

Return Value:

idnumber

listener id (this is needed to remove the listener)

Example:

const listenerId = map.addEventListener(MapWrapper.Event.CLICK, event => {
    map.addMarker({
        position: event.location
    });

    if(map.getMarkers().length > 10) {
        map.removeEventListener(MapWrapper.Event.CLICK, listenerId);
    }
})

addFeatures(features, [options]) experimental

Parameters:

featuresA GeoJSON object(required)

the features to add

optionsFeatureOptions(optional)

Return Value:

featuresarray of MapWrapper.Feature

the features that were added

We currently support GeoJSON of type "Feature" or "FeatureCollection", with the following geometries: "Point", "LineString", "MulitLineString", "Polygon" and "MultiPolygon" "GeometryCollection",

addMarker(marker)

Parameters:

markerMapWrapper.Marker or MarkerOptions(required)

Return Value:

markerMapWrapper.Marker

the added Marker object

fitMarkersToMap([markers])

Parameters:

markersarray of MapWrapper.Marker(optional)

markers to fit to the map (if none specified, the markers on the map will be used)

Return Value:

centerAndZoomCenterZoom

Finds a center location and zoom level such that all the markers on the map will be shown

getBounds()

Parameters:

none

Return Value:

boundsBounds

getCenter()

Parameters:

none

Return Value:

centerMapWrapper.Location

the center of the map

getDomElement()

Parameters:

none

Return Value:

elementElement

DOM element that the map is anchored to

getFeatures() experimental

Parameters:

none

Return Value:

featuresarray of MapWrapper.Feature

the features that are currently on the map

getId()

Parameters:

none

Return Value:

idstring

the id of the DOM element that the map is attached to

getMarkers()

Parameters:

none

Return Value:

markersarray of MapWrapper.Marker

the markers that are currently on the map

getProvider()

Parameters:

none

Return Value:

providerMapWrapper.Provider

the name of the provider for the wrapped map

getWrappedMap()

Parameters:

none

Return Value:

wrappedMapGoogle Map, Bing Map or OpenLayers Map

the wrapped map

IMPORTANT: this should only be used if there is some functionality that is needed but not provided by MapWrapper. You should expect to have to update any related code if you decide to change providers.

getZoom()

Parameters:

none

Return Value:

zoomnumber

current zoom of the map

removeEventListener(eventName, id)

Parameters:

eventNameMapWrapper.Event(required)

event name

idnumber(required)

listener id

Return Value:

none

Example:

const listenerId = map.addEventListener(MapWrapper.Event.CLICK, event => {
    map.addMarker({
        position: event.location
    });

    if(map.getMarkers().length > 10) {
        map.removeEventListener(MapWrapper.Event.CLICK, listenerId);
    }
})

removeFeatures(features) experimental

Parameters:

featuresarray of MapWrapper.Feature(required)

the features be removed

Return Value:

none

removeMarker(marker)

Parameters:

markerMapWrapper.Marker(required)

the marker to be removed

Return Value:

none

setBounds(bounds)

Parameters:

boundsBounds(required)

Return Value:

none

setCenter(center)

Parameters:

centerMapWrapper.Location or LocationLiteral(required)

new center of the map

Return Value:

none

Sets the center of the map to the specified location

setMarkers(markers)

Parameters:

markersarray of MapWrapper.Marker or array of MarkerOptions(required)

Return Value:

none

Removes all markers currently on the map, adds the specified markers to the map

setScrollWheelZoomEnabled(scrollWheelIsEnabled)

Parameters:

scrollWheelIsEnabledboolean(required)

Return Value:

none

Enables/disables scrollwheel zoom

setZoom(zoom)

Parameters:

zoomnumber(required)

new zoom for the map

Return Value:

none

Sets the zoom of the map to the specified zoom

setZoomControlPosition(position)

Parameters:

positionMapWrapper.PositionRelativeToMap(required)

Return Value:

none

Not currently supported by Bing

Events

BOUNDS_CHANGED

Arguments:

eventMapWrapper Event object

Fired when the map bounds change

CENTER_CHANGED

Arguments:

eventMapWrapper Event object

Fired when the map center changes

CLICK

Arguments:

eventMapWrapper Event object

Fired when a user clicks on the map

DRAG

Arguments:

eventMapWrapper Event object

Fired repeatedly while the map is being dragged

RIGHT_CLICK

Arguments:

eventMapWrapper Event object

Fired when a user right clicks on the map

ZOOM_CHANGED

Arguments:

eventMapWrapper Event object

Fired when the map zoom changes

Marker

Methods

constructor(options)

Parameters:

optionsMarkerOptions(required)

addEventListener(eventName, listener)

Parameters:

eventNameMapWrapper.Event(required)

name of the event to listen to

listenerfunction(required)

The function to be invoked when the event is triggered. The function will receive an Eventobject as an argument.

Return Value:

idnumber

listener id (this is needed to remove the listener)

addInfoWindow(content)

addInfoWindow(options)

Parameters:

contentHTML string or Element(required)

optionsInfoWindowOptions(required)

Return Value:

none

closeInfoWindow()

Parameters:

none

Return Value:

none

Closes the info window associated with the marker

getData()

Parameters:

none

Return Value:

dataJavaScript object

arbitrary data set previously

Returns the data object that was set on the marker

getLocation()

Parameters:

none

Return Value:

locationMapWrapper.Location

Returns the current latitude and longitude of the marker

getMap()

Parameters:

none

Return Value:

mapMapWrapper.Map

the map object that this marker belongs to

getProvider()

Parameters:

none

Return Value:

providerMapWrapper.Provider

provider name

getWrappedMarker()

Parameters:

none

Return Value:

wrappedMarkerGoogle Marker, Bing Pushpin or OpenLayers Feature

wrapped marker

isDraggable()

Parameters:

none

Return Value:

isDraggableboolean

draggable

openInfoWindow()

Parameters:

none

Return Value:

none

Opens the info window associated with the marker

removeEventListener(eventName, id)

Parameters:

eventNameMapWrapper.Event(required)

idnumber(required)

listener id

Return Value:

none

setColor(color)

Parameters:

colora hex color string(required)

Return Value:

none

Sets the color of the marker

setData(data)

Parameters:

dataJavaScript object(required)

arbitrary data

Return Value:

none

Stores arbitrary data with the marker

setDraggable(isDraggable)

Parameters:

isDraggableboolean(required)

draggable

Return Value:

none

setIcon(options)

Parameters:

optionsIconOptions(required)

Return Value:

none

Attaches the specified image to the marker

setLocation(location)

Parameters:

locationMapWrapper.Location or LocationLiteral(required)

Return Value:

none

Sets the marker to the specified location

setZIndex(zIndex)

Parameters:

zIndexnumber(required)

z index

Return Value:

none

Sets the marker to the specified zIndex (not currently supported by Bing)

updateInfoWindow(content)

updateInfoWindow(options)

Parameters:

contentHTML string or Element(required)

the content of the info window

optionsInfoWindowOptions(required)

Return Value:

none

Events

CLICK

Arguments:

eventMapWrapper Event object

Fires when the marker is clicked on

DOUBLE_CLICK

Arguments:

eventMapWrapper Event object

Fires when the marker is double clicked

DRAG

Arguments:

eventMapWrapper Event object

Fired repeatedly while the marker is being dragged

DRAG_END

Arguments:

eventMapWrapper Event object

Fires when the marker has finished being dragged

DRAG_START

Arguments:

eventMapWrapper Event object

Fires when the marker starts being dragged

MOUSEOUT

Arguments:

eventMapWrapper Event object

Fires when the mouse leaves the marker

MOUSEOVER

Arguments:

eventMapWrapper Event object

Fires when the mouse enters the marker

Location

In most cases MapWrapper.Location and LocationLiteral can be used interchangably.

Fields

latitudenumber

longitudenumber

Methods

constructor(latitude, longitude)

constructor(location)

Parameters:

latitudenumber(required)

longitudenumber(required)

locationLocationLiteral(required)

equals(location, [significantDigits])

Parameters:

locationMapWrapper.Location or LocationLiteral(required)

significantDigitsnumber(optional)

Return Value:

locationsAreEqualboolean

Returns true if and only if the latitude and longitude of the specified Location are equal (to the specified number of significant digits) to the latitude and longitude of this Location.

Event

Fields

eventNameMapWrapper.Event

locationMapWrapper.Location

The latitude and longitude where the event occurred. (Only included for mouse events)

providerEventvaries

The event object from the provider

targetMapWrapper.Map, MapWrapper.Marker or MapWrapper.Feature

The target that triggered the event

Feature experimental

Methods

addEventListener(eventName, listener) experimental

Parameters:

eventNameMapWrapper.Event(required)

name of the event to listen to

listenerfunction(required)

The function to be invoked when the event is triggered. The function will receive an Eventobject as an argument.

Return Value:

idnumber

listener id (this is needed to remove the listener)

Example:

const listenerId = feature.addEventListener(MapWrapper.Event.MOUSEOVER, e => {
    e.target.setStyle({
        strokeWeight: 5,
        strokeColor: "#000",
        fillColor: "#ff0000"
    });

    e.target.removeEventListener(
        MapWrapper.Event.MOUSEOUT,
        listenerId
    );
});)

getProvider() experimental

Parameters:

none

Return Value:

providerMapWrapper.Provider

provider name

getStyle() experimental

Parameters:

none

Return Value:

styleFeatureStyle

the style applied to the feature

getWrappedFeature() experimental

Parameters:

none

Return Value:

wrappedFeatureDepends on provider

The representation of the feature in the wrapped map.

Google: Google Feature
Bing: Bing Shape
OpenLayers: a JavaScript object with an OpenLayers layerand an OpenLayers feature.
Mapbox: a JavaScript object or an array of JavaScript objects with a Mapbox sourceand an array of Mapbox layer names.

removeEventListener(eventName, id) experimental

Parameters:

eventNameMapWrapper.Event(required)

event name

idnumber(required)

listener id

Return Value:

none

Example:

const listenerId = feature.addEventListener(MapWrapper.Event.MOUSEOVER, e => {
    e.target.setStyle({
        strokeWeight: 5,
        strokeColor: "#000",
        fillColor: "#ff0000"
    });

    e.target.removeEventListener(
        MapWrapper.Event.MOUSEOUT,
        listenerId
    );
});)

setStyle(style) experimental

Parameters:

styleFeatureStyle(required)

Return Value:

none

Example:

const polygon = map.addFeatures({
    "type": "Feature",
    "geometry": {
        "type": "Polygon",
        "coordinates": [[
            [ 60.0, 5.0 ],
            [ 65.0, 5.0 ],
            [ 65.0, 10.0 ],
            [ 60.0, 10.0 ],
            [ 60.0, 5.0 ]
        ]]
    }
})[0];

polygon.setStyle({
    strokeWeight: 1.5,
    strokeColor: "#333",
    fillColor: "#3e2e8e66"
})

Events

MOUSEOUT

Arguments:

eventMapWrapper Event object

Fires when the mouse leaves the feature

MOUSEOVER

Arguments:

eventMapWrapper Event object

Fires when the mouse enters the feature

Other types

Bounds

{
    northeast: {
        latitude: 37.4258,
        longitude: -121.8855
    },
    southwest: {
        latitude: 37.4122,
        longitude: -121.9199
    }
}

Attributes

northeastMapWrapper.Location or LocationLiteral(required)

the northeast boundary

southwestMapWrapper.Location or LocationLiteral(required)

the southwest boundary

CenterZoom

{
    center: {
        latitude: 37.4258,
        longitude: -121.8855
    },
    zoom: 12
}

Attributes

centerMapWrapper.Location or LocationLiteral(required)

the center of the map

zoomnumber(required)

the zoom level

FeatureOptions experimental

{
    style: {
        strokeColor: "darkred",
        fillColor: "#6f252599",
        strokeWeight: 2.5
    }
}

Attributes

styleFeatureStyle(optional)

FeatureStyle experimental

{
    strokeColor: "darkred",
    fillColor: "#6f252599",
    strokeWeight: 2.5
}

Attributes

fillColora hex color string(optional)

fill color for the features

strokeColora hex color string(optional)

stroke color for the features

strokeWeightnumber(optional)

stroke weight for the features

IconOptions

{
    icon: "./test_image.png",
    height: 32,
    width: 32
}

Attributes

heightnumber(required)

height of the specified image

iconstring(required)

url for the image

widthnumber(required)

width of the specified image

InfoWindowOptions

{
    content: `<div>
        <h4>Name of place</h4>
        <p>Some information about the place.</p>
    </div>`,
    openOn: Mapwrapper.Event.CLICK,
}

Attributes

contentstring, HTML string or Element(required)

the content of the info window

openOnMapWrapper.Event or array of MapWrapper.Event(optional)

default value: [ MapWrapper.Event.MOUSEOVER, MapWrapper.Event.CLICK ]

the events that will open the info window. Options are: MapWrapper.Event.MOUSEOVER or MapWrapper.Event.CLICK

orientationMapWrapper.InfoWindowOrientation(optional)

the orientation of the info window relative to the marker

LocationLiteral

{
    latitude: 37.4258,
    longitude: -121.8855
}

Attributes

latitudenumber(required)

longitudenumber(required)

MapOptions

{
    provider: MapWrapper.Provider.OPENLAYERS,
    elementId: "map",
    center: {
        latitude: 37.37500010085405,
        longitude: -121.98420524597164
    },
    zoom: 12,
}

Attributes

elementIdstring(required)

The id of the DOM element the map will be attached to.

providerMapWrapper.Provider(required)

The provider of the wrapped map.

centerMapWrapper.Location or LocationLiteral(required*)

The center of the map.

* Required if markers are not specified.

markersarray of MapWrapper.Marker or array of MarkerOptions(required*)

* Required if center and zoom are not specified. Specifying this parameter without specifying center and zoom should initialize the map such that all markers are in view

tileSourceMapWrapper.TileSource(required*)

The name of the tile source to use

* Required if the provider is MapWrapper.Provider.OPENLAYERS

zoomnumber(required*)

Zoom level for the map

* Required if markers are not specified.

attributionPositionMapWrapper.PositionRelativeToMap(optional)

NOTE: this option is only available when provider is either MapWrapper.Provider.OPENLAYERS or MapWrapper.Provider.MAPBOX_GL_JS

customAttributionHTML string(optional)

Additional attribution(s) to be shown on the map
NOTE: this option is only available when provider is either MapWrapper.Provider.OPENLAYERS or MapWrapper.Provider.MAPBOX_GL_JS

disableScrollWheelZoomboolean(optional)

maxZoomnumber(optional)

Maximum zoom level for the map

rasterTileSourceXYZ URL template string or array of XYZ URL template string(optional)

default value: https://api.nettoolkit.com/v1/geo/tiles/{z}/{x}/{y}?key=your_api_key_here

XYZ URL template string to a rasterTileSource. The URL should contain "{x}", "{y}", "{z}"
NOTE: at this time rasterTileSource is only supported for maps with provider set to MapWrapper.Provider.OPENLAYERS

showNetToolKitAttributionboolean(optional)

determines if an attribution is shown for NetToolKit
NOTE: this option only applies when the provider is set to MapWrapper.Provider.MAPBOX_GL_JS and NetToolKit tiles are being used.

vectorTileStyleURL string(optional)

default value: https://api.nettoolkit.com/geo/tiles/style/bright/style.json?key=your_api_key_here

URL string to a Mapbox style spefication document.
NOTE: at this time vectorTileStyle is only supported for maps with provider set to MapWrapper.Provider.MAPBOX_GL_JS

MarkerOptions

{
    provider: MapWrapper.Provider.GOOGLE,
    position: {
        latitude: 37.3791,
        longitude: -121.9834
    },
    color: "cyan",
    map: "map",
}

Attributes

locationMapWrapper.Location or LocationLiteral(required)

the location of the marker

mapMapWrapper.Map(required)

the map the marker belongs to

providerMapWrapper.Provider(required)

the provider of the wrapped marker

colora hex color string(optional)

color

dataJavaScript object(optional)

arbitrary data to be stored with the marker

iconIconOptions(optional)

options for an icon to use for this marker

infoWindowHTML string, Element or InfoWindowOptions(optional)

the content of the info window

Constants

Event

BOUNDS_CHANGED

CENTER_CHANGED

CLICK

DOUBLE_CLICK

DRAG

DRAG_END

DRAG_START

MOUSEOUT

MOUSEOVER

RIGHT_CLICK

ZOOM_CHANGED

InfoWindowOrientation

BOTTOM

LEFT

RIGHT

TOP

PositionRelativeToMap

BOTTOM_LEFT

BOTTOM_RIGHT

TOP_LEFT

TOP_RIGHT

Provider

BING

GOOGLE

MAPBOX_GL_JS

OPENLAYERS