bing-maps-loader

_A Promise based Microsoft Bing Maps Web control loader that supports Server Side Rendering (SSR)_


Installation

$3

``bash
$ yarn add bing-maps-loader
$ yarn add bingmaps # A Bing maps type library from Microsoft
`

$3

`bash
$ npm install bing-maps-loader --save
$ npm install bingmaps --save # A Bing maps type library from Microsoft
`

This project DOES NOT wrap the Microsoft.Map object, so use this directly after loading.

- BingMapsLoader - Loads the JS API from Bing directly. The Promise is resolved when loaded, or in the case it has already loaded, the Promise will resolve immediately. - Can be called multiple times. Will only initialize once. - Used to Hot load Bing Map modules - Promise based

https://docs.microsoft.com/en-us/bingmaps/v8-web-control/

Usage

After initializing, use the Microsoft.Maps object directly.

Note that if you wrap or proxy Microsoft.Maps , the this context may change and that can have weird breaking effects. e.g. _Type Errors_

$3

`js
import "bingmaps"; // <-- Microsoft supported types library for Microsoft.Maps
import { initialize, whenLoaded } from "bing-maps-loader";

const API_KEY = "[Your API Key]";

initialize(API_KEY);

// Creating a map and adding a pin after API has been loaded
function addPinToNewMap() {
// whenLoaded will resolve when the Map library is loaded
whenLoaded.then(() => {
const map = new Microsoft.Maps.Map("#map", { zoom: 6 }); // <-- can also use references e.g. Vue $refs, React.createRef()
const location = new Microsoft.Maps.Location(-39.2817, 175.5685);
const pin = new Microsoft.Maps.Pushpin((location, {
title: "Ruapehu",
subTitle: "Volcano",
text: "5",
});
//Add the pushpin to the map
map.entities.push(pin);
});
}
`

$3

#### 1. Register the script

Either in the HTML itself

`html

src="https://www.bing.com/api/maps/mapcontrol?callback=GetMapCallback&key=[MY API KEY]"
defer
async
>
`

Or using the provided getApiUrl with webpack

`js
const MAP_API_KEY = "ABCDEF";
import { getApiUrl } from "bing-maps-loader";
const mapJsUrl = getApiUrl(mapApiKey);

const htmlConfig = {
head: {
script: [
{
src: mapJsUrl,
defer: true,
async: true,
},
],
},
};
`

#### 2. OPTIONAL - Add this JS script in the head (or in a early loaded js)

If your JS code is late loading, then Microsoft Maps JS may have loaded before your code.
The Microsoft.Maps object can exist before the library is ready to be used.
Internally, the bing-maps-loader looks on the window object for a property of MicrosoftMapsLoaded, which is assigned by the following code:

`html

`

The above could also be called via a non-async, non-deferred JS script.


#### 3. Call initializeSSR() on both the server and the client

`js
import "bingmaps"; // <-- Microsoft supported types library for Microsoft.Maps
import { initializeSSR, whenLoaded } from "bing-maps-loader";

initializeSSR(); // should be called both on SSR AND in the client code

// Creating a map and adding a pin after API has been loaded
function addPinToNewMap() {
// whenLoaded will resolve when the Map library is loaded
whenLoaded.then(() => {
/ map code as per the non SSR example /
});
}
`

$3

Refer to Bing Maps Modules

`js
import "bingmaps";
import { initialize, whenLoaded, moduleNames } from "bing-maps-loader";

const createHeatMapLayer = async function (locations) {
await BingMapModuleLoader.loadModule(moduleNames.HeatMap);
return new Microsoft.Maps.HeatMapLayer(locations);
};
`

$3


Initialize the library on start up
`js
import { initialize } from "bing-maps-loader";
initialize("[ My API Key ]"); // if using SSR, read the instructions above.
`

Use the promises to handle the loading of the modules
`vue


`




Changelog

$3

- Testing a publish command a few too many times

$3

- Casing on module name was incorrect Microsoft.Maps.Autosuggest -> Microsoft.Maps.AutoSuggest

$3

- Change ModuleNames to moduleNames
- General clean

$3

- Documentation only. Typo: whenLoaded(), should be whenLoaded

$3

- SSR Race condition modification MicrosoftMapsLoaded

$3

- SSR Capability
- initialize method now returns void instead of a promise.
- Added whenLoaded`

$3

- Sweeping changes. No code stability.

Credits

Loosely copied off a promise based solution for loading JS, but I can't find the original source again!
If anyone knows, let me know.