GSMap | Documentation

Map Pooling for Gyroscope

gsmap.js is a map wrapper that's suited for Gyroscope and other single-page web apps.

Resource and Cost Efficiency

Each time "new google.maps.Map" is called, it counts towards Google JavaScript API's billing quota.

In a single-page web application where only one map is displayed at a time, it's inefficient to discard the map and recreate a new one after each use. For instance, on a property listing page, the map view should simply update its center and zoom level when a new location is selected, rather than generating a new map.

Gyroscope apps are single-page applications organized by tabs, and multiple maps can be loaded across these tabs. Theoretically, all tabs could share a single map instance since only one tab is visible at a time. However, since maps are often associated with markers and event listeners, it's more practical and efficient for each tab to maintain its own map instance.

When a tab is closed, it's a different matter. Instead of destroying the map, it should be "parked" for future use. This way, the map instance can be reused when another tab opens. The key idea behind gsmap.js is "map instance pooling". As tabs open and close during a Gyroscope user session, a limited number of map instances are created and reused, optimizing performance.

Unified Interface

The current gsmap.js prototype is built to support the Google Maps JavaScript API. In the future, the same gsmap_ functions will be compatible with other map libraries, with MapBox already on the roadmap. It's important to clarify that gsmap.js is not just another map manager offering syntactic shortcuts. Instead, it is a map instance pooling library that also provides the benefit of a unified interface.

Immediate Availability

Aligned with the philosophy of Progressive Enhancement, the current version of gsmap.js is production-ready, as long as the use cases are straightforward. By exposing raw objects, existing codebases only require partial adaptation while staying fully functional. Over time, additional gsmap_ functions will be introduced, offering more advanced parameters.

Simple Use

<div id="map" style="width:100%;height:300px"></div>
<script src="nano.js"></script>
<script src="gsmap.js"></script>
<script>
gsmap_apikey='YOUR_GOOGLE_MAP_API_KEY';
gsmap_getmap('map',43,-80,10);
</script>

Parking the Map

Before the container of a map is removed, the map can be "parked" for later use. This step is essential to map instance reuse.

In Gyroscope, a before-exit, or "bexit" function can be assigned to a tab:

reloadtab('client','','showclient?clientid='+clientid,
null, null,
{bexit: function(){
gsmap_freemap('clientmap_'+clientid);
}});

Callback

gsmap_getmap('map',43,-80,10,function(){
gsmap_addmarkers('map',
[{lat:43, lng:-80}]
);
});

Map Options

The default map options can be overwritten:

gsmap_getmap('map',43,-75,9,null,
{mapTypeControl:false}
);

A common mistake when porting Google Maps API to gsmap is to have "center" in the custom options. the following code won't work:

gsmap_getmap('map',43,-75,9,null,
{center: new google.maps.LatLng(43,-75)}
);

This is because gsmap.js loads Google Maps API on demand. google.maps is not instantiated until the first gsmap_getmap call.

Markers

gsmap.js adds markers in batches:

var markers=gsmap_addmarkers('map',
[
{lat:43, lng:-80},
{lat:35, lng:-120}
]
);

References to the added markers are returned to an array.
To add a single marker, use an array of one element. Remember that the function still returns an array:

var markers=gsmap_addmarkers('map',[...]);
var marker=markers[0];

Event Listeners

var lis=gsmap_addlistener('map','bounds_changed',function(){
...
});

Accessing Raw Map Object

The gsmap_getmap function attaches a "mapx" object to the target container. The mapx object, in turn, contains the mapobj element. In addition, mapx's container can be retrieved by mapx.mapview. This is useful as the container of the mapx object changes as the map slots rotate.

gid('map').mapx.mapobj.getCenter();
console.log(document.gsmaplot[0].mapx.mapview);

Map Grouping

The map instance pool can be further divided to sub groups. This is beneficial for maps with different styles or controls.

gsmap_getmap('map1',43,-80,10,null,null,'home_maps');
gsmap_getmap('map2',43,-80,10,null,null,'beach_maps');
gsmap_getmap('map3',43,-80,10,null,null,'home_maps');

Both map1 and map3 are in teh home_maps group; map2 will create and reserve its own map instance.