The Virtual Earth JavaScript control comes with a number of built-in controls including the zoom control and a control to set the map type. It is also possible to create your own custom controls in JavaScript. This article shows you how to create a simple layer selector control using the EcoMapCostaRica.com map as an example.

The custom control that we will add consists of a series of checkboxes that control the visibility of each map layer. Most of these are VELayer objects, although there is also a tile layer (name: 'aster'). The control can be minimized so that it does not take up much screen space.

The Virtual Earth API includes the VEMap.AddControl method. This can be used to add a custom HTML control to Virtual Earth. The sampe code in the SDK creates the control and then applies formatting using the Document Object Model (DOM). In order to work with the Virtual Earth 3d control, this method also inserts a 'shim' object between the VEMap div object and the custom control.

The SDK sample which inserts a left-aligned control works well. Unfortunately the CSS properties controlling right-alignment do not work correctly in Internet Explorer. Therefore we shall format the control using hard-coded CSS formatting.

In the header of our webpage, we defined the control's style like this:

ERROR [include_code_listing plugin]: File Not Found (/usr/www/users/winwaed/geowebguru/img/2009/ve_control_css.html)

Notice that we position the new control 20 pixels from the top and right margins of the parent object (the map's div). The control is white with a black border.

Next we define the following global variables in the JavaScript section of our page:

ERROR [include_code_listing plugin]: File Not Found (/usr/www/users/winwaed/geowebguru/img/2009/ve_control_globals.js)

Note that this article assumes the map object (VEMap) and the layer objects (VELayer) will be set before the rest of our code is called.

Now we are ready to define the JavaScript that populates, controls, and acts on our new control. Here it is:

ERROR [include_code_listing plugin]: File Not Found (/usr/www/users/winwaed/geowebguru/img/2009/ve_control_code.js)

The first two functions, ToggleLayer() and ToggleAster(), are callbacks from the control's checkboxes. These switch a layer on or off. ToggleLayer works on any VELayer (parameter ly). ToggleAster works on a tile layer which is referred to by name. Here we only have one tile layer, so the name is hard-coded. This could easily be passed as a parameter. We keep track of the tile layer status so that we can set the corresponding checkbox status correctly. We do not need to do this for the VELayer objects because these have an IsVisible() method that we can use instead.

The next two functions are setControlOpen() and setControlClose(). These open and close the control. They are also callbacks referenced by the 'x' in the upper right of the control: The closed control 'x' calls setControlOpen() and the open control 'x' calls setControlClose(). Both controls set the control's HTML content. The 'x' is implemented using a simple hyperlink. The checkboxes in the open control are implemented using a form. Each checkbox calls ToggleLayer or ToggleAster. The initial checkbox settings are set from VELayer.IsVisible() calls or the isAsterTileVisible variable.

We still use the shim so that Internet Explorer works correctly in Virtual Earth 3d. We need to explicitly resize the shim in setControlClose() so that it shrinks to match the new control size correctly. This is performed at the end of setControlClose().

The final two methods are AddLayerControl() and addShim(). AddLayerControl() should be called after the VEMap and all the layers have been created. It gets a reference to the control's div object, calls setControlOpen to populate it, and then calls addShim to create the shim. addShim() creates the shim and sets it to be the same size as the control.

All that remains to be done, is to create the control's div. This is performed with the following HTML:

ERROR [include_code_listing plugin]: File Not Found (/usr/www/users/winwaed/geowebguru/img/2009/ve_control_body.html)

Note that we also define the LoadPage() callback and the map's div. LoadPage() is not described here. This creates the Virtual Earth VEMap (map) object, creates the map layers, and then calls AddLayerControl() to create and display the new control using the myControl div.

Here are the results on the EcoMap Costa Rica map. This is what the control looks like when it is open:

And here it is closed:

Although the sample code in the Virtual Earth SDK works, it is limited to left-aligned controls. The above method fixes this problem. It also separates the control's CSS styling from the JavaScript.