JavaScript Maps SDK User Guide

Introduction

This document describes the features of the JavaScript^® Maps software development kit (SDK) application and demonstrates the usage of various application programming interfaces (APIs) on the map.

References

— JavaScript Maps SDK Reference Document

Map Parameters to Instantiate the Map Objects

The JavaScript Maps API comes with an object model which can be used to customize the map while instantiating map objects. The parameters listed in the following table are optional and can be declared during instantiation to customize the map for features like zoom, mapStyle, or center.

Table 1. Map Options
Parameter	Datatype	Default Value	Description
zoomDelta	Number	1	This value controls how the map’s zoom level changes, after zoomIn() or zoomOut() methods are called.
center	Array	undefined	Initial geographic center of the map
zoom	Number	undefined	Initial map zoom level
minZoom	Number	*	Minimum zoom level of the map
maxZoom	Number	*	Maximum zoom level of the map
mapStyle	String	default	Valid values are default or tosm.
zoomControl	Boolean	false	Valid values are true or false.

Note

zoomDelta values less than 1 allow greater granularity. When minZoom is not specified and at least one GridLayer or TileLayer is in the map, the lowest of their minZoom options are used. Similarly, when maxZoom is not specified and at least one GridLayer or TileLayer is in the map, the highest of their maxZoom options are used.

The major APIs are discussed in the following sections.

Map Operations

Map Operations

The following sections describe various map operations available in JavaScript Maps SDK.

Zoom

When a user scrolls a map, they can zoom the map by clicking the zoom controls. They can also zoom the map by using two-finger movements on the map for touchscreen devices, or with mouse on a desktop. The zoom control can be customized as shown in Zoom Configuration Parameters.

Zoom Configuration Parameters

By default zoomControl is set to false in the map. If the user wants to turn it on, zoomControl needs to be set to true and the property, defaults, needs to be passed during map initialization as shown in the following code snippet.

const defaults = {
zoomControl:true,
}
new gssmaps.GSSMap('<PUT_YOUR_API_KEY_HERE>', 'map', defaults);

The following configuration parameters allow you to set the available zoom options for the map.

const defaults = {
	 zoomControl: false,

      /* set zoom levels */
      minZoom: 0,
      maxZoom: 22,
      zoomDelta: 0.25

    }

Zoom controls are shown in the figure; + denotes zoom in and - denotes zoom out.

Figure 1. Zoom Control Options

Zoom Control Programming

Zoom options can be controlled by programming. They include zoom level, minimum and maximum zoom levels, zoom in and zoom out.

Set Zoom Level

You can program the zoom level of the current map to a desired number, as shown in the following example. The map can be zoomed out or zoomed in to this zoom level.

gssMap.setZoom(12);

Set Maximum and Minimum Zoom Levels

The map can be set to maximum or minimum zoom levels by executing following code snippets. If the map’s current zoom level is higher than the new maximum, the map will zoom to the new maximum and if current zoom level is lower than the new minimum, the map will zoom to the new minimum.

gssmap.setMaxZoom(20);

gssmap.setMinZoom(0);

Important

You can increase or decrease the zoom level by the default value set for zoomDelta. If no value is set for zoomDelta, then the the zoom level either increases or decreases by 0.25, whenever the user double clicks on the map or uses zoomin (+) or zoomout (-) options displayed in the preceding figure.

Pan

The user can pan/move the map using two-finger movements on the map for touchscreen devices, or with mouse on a desktop. The following methods are supported for Pan in JavaScript Maps SDK.

PanTo

The map can be panned to a given center by executing the following code snippet.

var gssLatLng = new gssmaps.GSSLatLng(17.4126274,78.2679571);
gssMap.panTo(gssLatLng);

SetView

The setView method works similar to PanTo with an additional option to zoom, which can be set using latitude, longitude and a zoom level as shown in the following code snippet.

var gssLatLng = new gssmaps.GSSLatLng(40.6079107,-73.9453283);
gssMap.setView(gssLatLng, 10);

In the above code snippet, 10 indicates zoom level.

Markers

A marker identifies a location on a map. Using this API, you can add custom icons or markers to the map and turn them on or off as desired.

Markers can be converted to custom images, in which case, they are usually referred to as "icons." To make default images of markers function properly, you must place the "assets" folder, highlighted in the screenshot below in the same path where, gssmaps.min.js file is placed in your local drive, after extraction.

Figure 2. Assets Folder and gssmaps.min.js Placement

The markers are illustrated on this map.

Figure 3. Markers

The following sections explain various functions of markers with examples.

Add a Marker

The following code snippet adds a marker.

var gssLatLng = new gssmaps.GSSLatLng(17.4126274,78.2679571);
var gssMarker = new gssmaps.GSSMarker(gssLatLng);
gssMap.addMarker(gssMarker, popupContent);

Note	popupContent is an optional string variable passed. This allows for the content to be displayed when the user clicks on a marker.

Add a Custom Marker

The following code snippet adds a custom marker.

var gssLatLng = new gssmaps.GSSLatLng(40.6079107,-73.9453283);
var gssIcon = new gssmaps.GSSIcon("assets/bus-marker.png", [32, 32], [16, 32]);
var options = {"icon" : gssIcon};
var gssMarker = new gssmaps.GSSMarker(gssLatLng, options);
gssMap.addMarker(gssMarker, popupContent);

Custom markers are shown in the following figure.

Figure 4. Custom Marker

A smaller sized custom marker can also be added by reducing the value of height and width attributes in the GSSIcon class. The attributes for GSSIcon class are as follows.

GSSIcon(iconUrl, height and width, tip)

Remove Marker

The following code snippet removes a single marker.

gssMap.removeMarker(gssMarker);

Remove All Markers

This code snippet removes all markers.

gssMap.removeAllMarkers();

Polyline

A polyline is a connected sequence of line segments between consecutive points created as a single object. It can be added from JSON file/object to a map as shown in the following code snippet.

var gssLatLngs = new Array();
$.each(defaultline, function(idx, value){
gssLatLngs.push(new gssmaps.GSSLatLng(value.lat, value.lng));
        });

gssMap.addPolyline(new gssmaps.GSSPolyline(gssLatLngs));

Polyline options can also be added to map by giving values to the property "GSSLineOptions". The color and width of the polyline can be adjusted as shown in the following code snippet. GSSLineOptions supports three formats for color.

A color name like "'red", "blue" or "green" and so on.
HEX code—hexadecimal numbers with 6 digits like 999392.
RGB color code pattern, for instance, RGB 153, 147, 146.

var lineOptions = new gssmaps.GSSLineOptions('red', 5);
gssMap.addPolyline(new gssmaps.GSSPolyline(gssLatLngs, lineOptions));

The following figure shows the polyline added in a map.

Figure 5. Adding Polyline

JavaScript SDK