Bing Maps V6.x To V8 Shim

Bing Maps (formerly known as Virtual Earth) was deprecated in November of 2016 and will be taken offline in August of 2017. This project wraps Bing Maps V8 and exposes an API that is very similar to Bing Maps V6.x. In many cases this shim can be implemented in an existing application using Bing Maps 6.x with a only few lines of code and provide majority of the v6.x functionality on a Bing Maps V8 web control.

This shim has some known limitations and is only meant to help keep applications that are using Bing Maps v6.x running long enough for developers to be fully migrated their applications to Bing Maps V8. This should not be condsidered a long term solution. See the Bing Maps V6.3 to V8 Migration Guide for detailson how to migrate your app.

How to implement

Implementing this solution requires the following steps:

Download the BingMapsV63ToV8Shim.js file from the dist folder or this project.
Add this file to your application like you would any other JavaScript file.
Locate the script tag in your application which loads the Bing Maps V6.3 web control. It will look something like one of the following, but may have additional query parameters in the URL.

<script type="text/javascript" src="http://dev.virtualearth.net/MapControl/mapcontrol.ashx?v=6.3"></script>

<script type="text/javascript" src="http://ecn.dev.virtualearth.net/MapControl/mapcontrol.ashx?v=6.3"></script>

<script type="text/javascript" src="https://dev.virtualearth.net/MapControl/mapcontrol.ashx?v=6.3&s=1"></script>

<script type="text/javascript" src="https://ecn.dev.virtualearth.net/MapControl/mapcontrol.ashx?v=6.3&s=1"></script>

Replace this map script tag with the following script tag.

<script type='text/javascript' src='https://www.bing.com/api/maps/mapcontrol'></script>

Right after the map script tag add an additional script tag that points to where the BingMapsV63ToV8Shim.js file is hosted in your application.

<script type="text/javascript" src="scripts/BingMapsV63ToV8Shim.js"></script>

Note that you will need to change the URL path to point to the proper location in your application.

Ensure proper authenication is implemented

It is important to ensure that your application is properly implementing authenication. V6.x required the map to be authenicated but did not display any warnings when this was not done. Bing Maps V8 will display a warning over top of the map if a Bing Maps key is not specified when loading the map.

In your code, find where the VEMap class is created and also where the LoadMap function of that class is being called. Between these two lines of code should be call to the SetCredentials function. Here is what this should look like:

var map = new VEMap('myMap');
map.SetCredentials('Your Bing Maps Key');
map.LoadMap();

If you do not see the call to the SetCredentials function, your application is not properly implementing authenication. Add this line of code as shown above and add your Bing Maps key. You can find your Bing Maps key in the Bing Maps portal by going to My Account -> My Keys.

If you do not see any keys listed you can create a new key.
If you do not have a Bing Maps account, press the sign in button on the Bing Maps portal to create an account.
If you know you have an account but cannot access it or need to change the login details associated with it, please follow these steps.

Example Implementation

Before - using V6.x

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
    <title>Core Map Control Sample</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

    <script type="text/javascript" src="http://ecn.dev.virtualearth.net/MapControl/mapcontrol.ashx?v=6.3"></script>

    <script type="text/javascript">
    var map = null;
    function GetMap()
    {
        map = new VEMap('myMap');
        map.SetCredentials('Your Bing Maps Key');
        map.LoadMap();
    }
    </script>
</head>
<body onload="GetMap();">
    <div id='myMap' style="position:relative; width:800px; height:600px;"></div>
</body>
</html>

After - Shimmed and uses V8

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
    <title>Core Map Control Sample</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

    <script type='text/javascript' src='https://www.bing.com/api/maps/mapcontrol'></script>
    <script type="text/javascript" src="scripts/BingMapsV63ToV8Shim.js"></script>

    <script type="text/javascript">
    var map = null;
    function GetMap()
    {
        map = new VEMap('myMap');
        map.SetCredentials('Your Bing Maps Key');
        map.LoadMap();
    }
    </script>
</head>
<body onload="GetMap();">
    <div id='myMap' style="position:relative; width:800px; height:600px;"></div>
</body>
</html>

Common Issues

Bing Maps V8 is designed to be an asynchronous control. As such it loads a lot of additional resources in the background without blocking the main UI thread. However, this means that the map API isn't available to your code until the onload event of the page body has fired. Any JavaScript code that tries to access the map API before the onload event fires will throw an error as it won't recognive the code. This will most likely happen if you have any global variables that are initialized with an object from the map API. To address this, define the variables as null and set them in the callback function for the onload event.

Known Limitations

Only Bing Maps V8 supported browsers will support this shim.
Some features require using the experimental branch of the V8 control, primarily the ImportShapeLayerData function which imports KML and GeoRSS files. Add ?branch=experimental to the map script URL. This should only be the case until the August update to the Bing Maps V8 web control.
No support for HTML based pushpins. Pushpins should fall back to the default pushpins in Bing Maps V8 (purple circles).
CSS hacks used in v6.3 won’t work.
Events will only honor the last attached event of a certain type. For example, if your application attaches two click events to the map, only the last attached event will be fired.
No support for preventing event bubbling/propagation. In v6.3 you could return false in an event handler and it would prevent event from triggering any other events that would normally fire with that event.
The infobox box will use the V8 default infobox.
3D maps not supported. Note that the 3D maps were deprecated in 2010.
Birdseye only partially supported through API.
There are many functions and classes that are not exposed for various reasons. These are clearly marked in the source code as “not supported”.

Additional Resources

License

MIT

See License for full license text.

rbrundritt / BingMapsV63ToV8Shim