The MapAPI 1.0 is deprecated. Please use the new MapAPI 1.1.

infoware mapsuite Javascript API - Company for Mapping, Routing, GPS-Navigation, Tracking and Telematics solutions

« Previous chapter 5: Controls Back to Index Next chapter 7: Shapes and Layers »

Chapter 6: Overlays

In this section we give you a detailed introduction about our overlay concept. Our IWOverlay interface makes it possible to add user-defined content to your map.

With overlays we are able to mark points on the map we are interested in. With a few simple statements we are able to add arbitrary markers to the map, add descriptions and define settings like in which scale the marker should be visible. In our examples we will build a marker in three steps. We start with the simplest possible overlay, then we will customize it a little bit, and add description to it. Finally we will define an own overlay which we will add to the map.

6.1 Adding a simple overlay

This example will show our company, with a small house as overlay located at the street "Riemenschneiderstraße".

Overlay example 6a (view example):

Source code example 6a:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<html>
	<head>		
		<title>Chapter 6: Overlays example 6a</title>
		<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">		
		
		<script type="text/javascript" src="http://iw.mapandroute.de/MapAPI-1.0/js/mapping.js"></script>
		
		<script type="text/javascript">
		
			function initialize()
			{
				var map = new IWMap(document.getElementById('map'));

				var icon = new IWIcon('http://iw.mapandroute.de/MapAPI-1.0/img/symbols/house/house_red_30.gif', new IWPoint(15, 13), new IWSize(30, 26));  
				   
				var marker = new IWMarker(map, new IWCoordinate(7.1408879, 50.70150837, IWCoordinate.WGS84).toMercator());				
				marker.setDefaultIcon(icon);
				
				IWEventManager.addListener(map, 'oninitialize',
					function() {
						map.getOverlayManager().getLayer(0).addOverlay(marker);
					}
				);
				
				map.setCenter(new IWCoordinate(7.1408879, 50.70150837, IWCoordinate.WGS84));
			}
	
		</script>	
	</head>
	
	<body onload="initialize();">
		<div id="map" style="background-color: #dddddd; width: 450px; height: 300px"></div>
	</body>
</html>

The code shows there are only a few new lines:

var marker = new IWMarker(map, new IWCoordinate(267470.8, 214348.5));
marker.setDefaultIcon(icon);

Here we want to set our first marker. We instantiate IWMarker with an MERCATOR-Coordinate. If you don't know what a MERCATOR-Coordinate is about, or how to determine them, please have a look at the previous chapter geocoding.

IWEventManager.addListener(map, 'oninitialize',
function() {

With this listener we can make sure that our markers are not shown too early. The function will be executed after the map is loaded.

map.getOverlayManager().getLayer(0).addOverlay(marker);

Similar to the IWLayoutManager, there is an IWOverlayManager for the overlays. Accordingly we have to specify a layer where we want to add the marker. The higher the number for the layer is, the more in front are the overlays. We choose the lowest layer (0) and add our marker with the method addOverlay().

6.2 Customizing the marker

We will take our previous example and adjust the look a little bit.

Overlay example 6b (view example):

Source code example 6b:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<html>
	<head>		
		<title>Chapter 6: Overlays example 6b</title>
		<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">		
		<script type="text/javascript" src="http://iw.mapandroute.de/MapAPI-1.0//js/mapping.js"></script>
		<script type="text/javascript">
		
			function initialize()
			{
				var map = new IWMap(document.getElementById('map'));

				map.getLayoutManager().getLayer(0).addControl(new IWSliderControl(map), IWAlignment.RIGHT, IWAlignment.BOTTOM, 0, 0);
				
				var redIcon30 =  
					new IWScaleDependentIcon('http://iw.mapandroute.de/MapAPI-1.0/img/symbols/house/house_red_30.gif', 
						new IWPoint(15, 13), new IWSize(30, 26), new IWRange(17, 19));
					
				var redIcon26 = 
					new IWScaleDependentIcon('http://iw.mapandroute.de/MapAPI-1.0/img/symbols/house/house_red_26.gif', 
						new IWPoint(15, 13), new IWSize(30, 26), new IWRange(14, 16));
					
				var redIcon22 = 
					new IWScaleDependentIcon('http://iw.mapandroute.de/MapAPI-1.0/img/symbols/house/house_red_22.gif', 
						new IWPoint(15, 13), new IWSize(30, 26), new IWRange(11, 13));
						
				var redIcon18 = 
					new IWIcon('http://iw.mapandroute.de/MapAPI-1.0/img/symbols/house/house_red_18.gif', 
						new IWPoint(15, 13), new IWSize(30, 26));		

				var marker1 = new IWMarker(map, new IWCoordinate(7.141279, 50.70250, IWCoordinate.WGS84).toMercator());
				marker1.setDefaultIcon(redIcon18);		
				marker1.addScaleDependentIcon(redIcon30);
				marker1.addScaleDependentIcon(redIcon26);
				marker1.addScaleDependentIcon(redIcon22);
				
				map.getOverlayManager().getLayer(0).setVisibilityRange(new IWRange(10, 19));
				
				var orangeIcon30 = 
					new IWScaleDependentIcon('http://iw.mapandroute.de/MapAPI-1.0/img/symbols/house/house_purple_30.gif',
						new IWPoint(15, 13), new IWSize(30, 26), new IWRange(17, 19));
				
				var orangeIcon26 = 
					new IWScaleDependentIcon('http://iw.mapandroute.de/MapAPI-1.0/img/symbols/house/house_purple_26.gif',
						new IWPoint(15, 13), new IWSize(30, 26), new IWRange(14, 16));
				
				var orangeIcon22 = 
					new IWScaleDependentIcon('http://iw.mapandroute.de/MapAPI-1.0/img/symbols/house/house_purple_22.gif',
						new IWPoint(15, 13), new IWSize(30, 26), new IWRange(11, 13));
				
				var orangeIcon18 = 
					new IWIcon('http://iw.mapandroute.de/MapAPI-1.0/img/symbols/house/house_purple_18.gif',
						new IWPoint(15, 13), new IWSize(30, 26));		

				var marker2 = new IWMarker(map, new IWCoordinate(7.141579, 50.701750, IWCoordinate.WGS84).toMercator());								
				marker2.setDefaultIcon(orangeIcon18);		
				marker2.addScaleDependentIcon(orangeIcon30);
				marker2.addScaleDependentIcon(orangeIcon26);
				marker2.addScaleDependentIcon(orangeIcon22);
				
				map.getOverlayManager().getLayer(1).setVisibilityRange(new IWRange(9, 19));
						
				IWEventManager.addListener(map, 'oninitialize',
					function()
					{
						map.getOverlayManager().getLayer(0).addOverlay(marker1);
						map.getOverlayManager().getLayer(1).addOverlay(marker2);						
					}
				);
				
				map.setCenter(new IWCoordinate(7.1408879, 50.70150837, IWCoordinate.WGS84));
			}
		</script>	
	</head>
	
	<body onload="initialize();">
		<div id="map" style="background-color: #dddddd; width: 450px; height: 300px"></div>
	</body>
</html>

Here we changed the marker icon and set additional icons for different scales.

var icon30 = new IWIcon('http://iw.mapandroute.de/MapAPI-1.0/img/symbols/house/house_red_30.gif', new IWPoint(15, 13), new IWSize(30, 26));

We define a new icon with IWIcon. As first parameter we have to set the URL of the icon we want to show on the map. The second parameter sets the image hotspot. The hotspot is the point which will lie exactly on the given coordinate. The point is set relative to the upper left corner. If there isn't a second parameter given, the hotspot will be the upper left corner. In our example, our house has a size of 30x26 pixel. We want the house centered on the coordinate, so we set the hotspot to 15x13 pixel.

You can use your own images as icons, or you can use our image database. Here you can get an overview of the images available.

marker1.setDefaultIcon(redIcon18);

With setDefaultIcon() we can change the image of the marker.

marker1.addScaleDependentIcon(redIcon30);
marker1.addScaleDependentIcon(redIcon26);
marker1.addScaleDependentIcon(redIcon22);

We can add different IWScaleDependentIcons for different scale levels. In this example we are using smaller icons for higher scales. The redIcon22 in this example is shown if the map has a zoomlevel between 11 and 13. If there would be more icons for the same scale, the first added icon would be shown.

map.getOverlayManager().getLayer(0).setVisibilityRange(new IWRange(10, 19));

With the method setVisibilityRange() you can specify in which zoom levels the layer will be shown.

Note: If you want to get a feeling what values of zoom levels look like, you can use the method getZoom() from the IWMap object. The code below shows the current zoomlevel after each zoom:

IWEventManager.addListener(map, 'onzoomend',
	function()
	{
		alert(map.getZoom());
	}
);

6.3 Adding descriptions

In this section we will discuss how to add special behaviors to our marker. The following example will add a user-defined tooltip and a window balloon to our marker, which will be shown when the mouse is over the marker.

Overlay example 6c (view example):

Source code example 6c:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<html>
  <head>
    <title>Chapter 6: Overlays example 6c</title>
    <script type="text/javascript" src="http://iw.mapandroute.de/MapAPI-1.0/js/mapping.js"></script>
    <script type="text/javascript">

			function initialize()
			{
				//********************************************************************
				// Creates the map object and set the center
				//********************************************************************  
				var map = new IWMap(document.getElementById('divMap'));

				//********************************************************************
	  			// Adds controls and markers after the map has been loaded
	  			//********************************************************************
	  			IWEventManager.addListener(map, 'oninitialize',
					function(e)
					{
						map.getLayoutManager().getLayer(0).addControl(new IWSliderControl(map), IWAlignment.RIGHT, IWAlignment.BOTTOM, 0, 0);
						map.getLayoutManager().getLayer(0).addControl(new IWScalarControl(map), IWAlignment.BOTTOM, IWAlignment.LEFT, 0, 0);

						//********************************************************************
						//* Creates a overlay with a tooltip
						//********************************************************************
						var marker1 = new IWMarker(map, new IWCoordinate(7.141279, 50.70250, IWCoordinate.WGS84).toMercator());

	    				IWEventManager.addListener(marker1, 'onmouseover',
							function(e)
							{
								map.openTooltip(this.getCoordinate(), 'My first tooltip...');
	        					var listener = IWEventManager.addListener(marker1.getContainer(), 'onmouseout',
									function(e)
									{
		       							map.removeTooltip();
		        						IWEventManager.removeListener(listener);
	       							}.iwclosure(this)
								);	      					
	    					}.iwclosure(marker1)
						);

	    				//********************************************************************
						// Creates a overlay with an infoballoon
						//********************************************************************
						var marker2 = new IWMarker(map, new IWCoordinate(7.141579, 50.701750, IWCoordinate.WGS84).toMercator());

	    				IWEventManager.addListener(marker2, 'onclick',
							function(e)
							{
								map.openInfoBalloon(this.getCoordinate(), 'Hello <b>World</b>');
								
	    					}.iwclosure(marker2)
						);

						var overlayLayer = map.getOverlayManager().getLayer(0);
						overlayLayer.addOverlay(marker1);
						overlayLayer.addOverlay(marker2);						
    				}
				);
				map.setCenter(new IWCoordinate(7.1408879, 50.70150837, IWCoordinate.WGS84));
    	}
	</script>
  </head>
  <body onload="initialize();">
    <div id="divMap" style="background-color: #dddddd; width: 450px; height: 300px"></div>
  </body>
</html>

In this example we changed the structure a little bit. To make sure the map is loaded before we add our controls and overlays, we put all the code in the function that will be executed after the listener has fetched the 'oninitialize' event.

IWEventManager.addListener(marker1, 'onmouseover',
function(e)
{
	map.openTooltip(this.getCoordinate(), 'My first tooltip...');
	var listener = IWEventManager.addListener(marker1.getContainer(), 'onmouseout',
		function(e)
		{
			map.removeTooltip();
			IWEventManager.removeListener(listener);
		}.iwclosure(this)
	);	      					
}.iwclosure(marker1));

We add the listener onmouseover to our marker. If this event is catched, we create a tooltip and add it on the map by calling the map.openTooltip() method. If you want to create your own openTooltip() mechanism you should have a closer look to the IWTooltip class and the addWindowOverlay() method.

After we have added our tooltip, we have to add a new listener onmouseout to our marker to destroy it when the mouse is gone. We remove the marker with map.removeTooltip(). Finally we remove our onmouseout listener to keep the memory clean of unused objects.

IWEventManager.addListener(marker2, 'onclick',
	function(e)
	{
		map.openInfoBalloon(this.getCoordinate(), 'Hello <b>World</b>');							
	}.iwclosure(marker2)
);

In this example we wanted to use html-code for the information in our infoballoon. We add a listener to the onclick event of our marker. If this event is triggered we open the infoballoon with map.openInfoBalloon(). If you want to create your own openInfoBalloon mechanism you should have a look to the IWInfoBalloon class and the addWindowOverlay() method.

6.4 Creating your own overlay

Similar to the controls you can create your own overlay. You just have to implement the IWOverlay interface in your own class. Once this is done, you automatically have several standard methods for visibility, draggability etc. You can get detailed information from the documentation. The most important methods will be introduced in our example.

Overlay example 6d (view example):

Source code example 6d:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<html>
	<head>		
		<title>Chapter 6: Overlays example 6d</title>		
		
		<script type="text/javascript" src="http://iw.mapandroute.de/MapAPI-1.0/js/mapping.js"></script>
		
		<script type="text/javascript">
		
			function MyMarker(map, coordinate)
			{
				IWOverlay.call(this, map, coordinate);
				var container = this.getContainer();
				
				var img = document.createElement('img');
				container.appendChild(img);
				 
				img.ondrag = function() { return false; };
				img.src = 'http://iw.mapandroute.de/MapAPI-1.0/js/iwAPI/examples/tutorial/img/pin.gif';
	
				this.setHotspot(new IWPoint(4, 33));
				this.setDraggable(true);				
			}
		
			function initialize()
			{
				var map = new IWMap(document.getElementById("map"));
				var marker = new MyMarker(map, new IWCoordinate(7.141579, 50.701750, IWCoordinate.WGS84).toMercator());
				
				IWEventManager.addListener(marker, 'onpositionchange', 
					function(e)
					{
						var coord = marker.getCoordinate();
						alert('new position after dragging: ' + coord.getX() + ', ' + coord.getY());		
					}
				);			
			
				IWEventManager.addListener(map, 'oninitialize',
					function()
					{
						map.getLayoutManager().getLayer(0).addControl(new IWSliderControl(map), IWAlignment.RIGHT, IWAlignment.TOP, 0, 0);
						map.getOverlayManager().getLayer(0).addOverlay(marker);
					}
				);
				
				map.setCenter(new IWCoordinate(7.1408879, 50.70150837, IWCoordinate.WGS84));
			}
	
		</script>	
	</head>
	
	<body onload="initialize();">
		<div id="map" style="background-color: #dddddd; width: 450px; height: 300px"></div>
	</body>
</html>

Creating an own overlay just takes a few simple steps:

function MyMarker(map, coordinate)
{

Here we define our new class. We define it with a parameter for the coordinate, so if you use it later you can add it to different positions.

IWOverlay.call(this, map, coordinate);
var container = this.getContainer();

The most important thing to do when making an overlay is to call the IWOverlay interface. The interface takes a coordinate (where the marker should appear) as parameter. After calling the interface we can get the div we can work with with the method this. getContainer(). As mentioned above there are several new methods available for common functionality. For a detailed listing have a look in our class documentation.

var img = document.createElement('img');
container.appendChild(img);
img.ondrag = function() { return false; };
img.src = 'http://iw.mapandroute.de/MapAPI-1.0/js/iwAPI/examples/tutorial/img/pin.gif';

In our example we want to add our own image, a pin. So we simply create it and append it to our container.

this.setHotspot(new IWPoint(4, 33));

We set the hotspot (the point in the image where the coordinate will be set to) to the tip of our pin.

this.setDraggable(true);

We want our new marker to be draggable, so we just use the predefined method setDraggable() with the parameter true. The default value is set to false.

And thats all. After we have defined our overlay we can use it like an usual overlay.

6.5 Removing overlays

Removing overlays is very simple. The only thing that we have to do is to call either one of the remove methods from the IWOverlayLayer or IWOverlayManager class.

The removeAllOverlays method from the IWOverlayLayer class removes all overlays from the specified layer. If you want to remove a single overlay you should call the removeOverlay method with the overlay object as a parameter. Additional the IWOverlayManager contains two methods for removing layers. If you want to remove a whole layer from the map you can use the removeLayer method. This method requires the layer id as a parameter. In some cases it is necessary to remove all overlay layers at the same time. To do this, you can use the removeAllLayers method.

The following example demonstrates the use of the remove methods:

Overlay example 6e (view example):

Source code example 6e:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<html>
	<head>
		<title>Chapter 6: Overlays example 6e</title>
		<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
		<script type="text/javascript" src="http://iw.mapandroute.de/MapAPI-1.0/js/mapping.js"></script>
		
		<script type="text/javascript">
		
			var map = null;
			var marker1 = null;
			var marker2 = null;
			var marker3 = null;
			var marker4 = null;
			var marker5 = null;
			var marker6 = null;
			var marker7 = null;
			var marker8 = null;

			function initialize()
			{
				map = new IWMap(document.getElementById("map"));				
				map.getLayoutManager().getLayer(0).addControl(new IWSliderControl(map), IWAlignment.RIGHT, IWAlignment.BOTTOM, 0, 0);
							
			  	marker1 = new IWMarker(map, new IWCoordinate(7.143579, 50.72375, IWCoordinate.WGS84).toMercator());
			  	marker2 = new IWMarker(map, new IWCoordinate(7.161681, 50.70175, IWCoordinate.WGS84).toMercator());
			  	marker3 = new IWMarker(map, new IWCoordinate(7.142439, 50.71425, IWCoordinate.WGS84).toMercator());
			  	marker4 = new IWMarker(map, new IWCoordinate(7.130475, 50.71234, IWCoordinate.WGS84).toMercator());
			  	marker5 = new IWMarker(map, new IWCoordinate(7.151401, 50.70884, IWCoordinate.WGS84).toMercator());
			  	marker6 = new IWMarker(map, new IWCoordinate(7.151557, 50.71163, IWCoordinate.WGS84).toMercator());
			  	marker7 = new IWMarker(map, new IWCoordinate(7.142019, 50.70181, IWCoordinate.WGS84).toMercator());
			  	marker8 = new IWMarker(map, new IWCoordinate(7.153521, 50.72202, IWCoordinate.WGS84).toMercator());

				IWEventManager.addListener(map, 'oninitialize',
					function()
					{
						addMarkers();
					}
				);
				
				map.setCenter(new IWCoordinate(7.1408879, 50.70150837, IWCoordinate.WGS84), 11);
			}
			
			function addMarkers()
			{
				if (!marker1.isDisplayed())
					map.getOverlayManager().getLayer(0).addOverlay(marker1);
				if (!marker2.isDisplayed())
					map.getOverlayManager().getLayer(0).addOverlay(marker2);
				if (!marker3.isDisplayed())
					map.getOverlayManager().getLayer(0).addOverlay(marker3);
				if (!marker4.isDisplayed())
					map.getOverlayManager().getLayer(1).addOverlay(marker4);
				if (!marker5.isDisplayed())					
					map.getOverlayManager().getLayer(1).addOverlay(marker5);
				if (!marker6.isDisplayed())					
					map.getOverlayManager().getLayer(2).addOverlay(marker6);
				if (!marker7.isDisplayed())					
	        		map.getOverlayManager().getLayer(2).addOverlay(marker7);
        		if (!marker8.isDisplayed())					
				  	map.getOverlayManager().getLayer(3).addOverlay(marker8);
			}
			
			function removeSingleOverlayExample()
			{
				map.getOverlayManager().getLayer(0).removeOverlay(marker2);
			}

			function removeAllOverlaysExample()
			{
				map.getOverlayManager().getLayer(1).removeAllOverlays();
			}
			
			function removeLayerExample()
			{
				map.getOverlayManager().removeLayer(2);
			}
			
			function removeAllLayersExample()
			{
				map.getOverlayManager().removeAllLayers();
			}
	
		</script>	
	</head>
	
	<body onload="initialize();">
		<div id="map" style="background-color: #dddddd; width: 450px; height: 300px"></div>
		<br>
		<input type="button" name="addMarkers" value="addMarkers" onclick="addMarkers()"></input>		
		<input type="button" name="removeOverlay" value="removeOverlay" onclick="removeSingleOverlayExample()"></input>
		<input type="button" name="removeAllOverlays" value="removeAllOverlays" onclick="removeAllOverlaysExample()"></input>
		<input type="button" name="removeLayer" value="removeLayer" onclick="removeLayerExample()"></input>
		<input type="button" name="removeAllLayers" value="removeAllLayers" onclick="removeAllLayersExample()"></input>
	</body>
</html>

At the beginning of our example we added a couple of IWMarker`s to our map. Notice that some of the markers are placed on different layers.

...
if (!marker1.isDisplayed())
  map.getOverlayManager().getLayer(0).addOverlay(marker1);
if (!marker2.isDisplayed())
  map.getOverlayManager().getLayer(0).addOverlay(marker2);
if (!marker3.isDisplayed())
  map.getOverlayManager().getLayer(0).addOverlay(marker3);
if (!marker4.isDisplayed())
  map.getOverlayManager().getLayer(1).addOverlay(marker4);
if (!marker5.isDisplayed())					
  map.getOverlayManager().getLayer(1).addOverlay(marker5);
if (!marker6.isDisplayed())					
  map.getOverlayManager().getLayer(2).addOverlay(marker6);
if (!marker7.isDisplayed())					
  map.getOverlayManager().getLayer(2).addOverlay(marker7);
if (!marker8.isDisplayed())					
  map.getOverlayManager().getLayer(3).addOverlay(marker8);
...

We added five buttons below the map to test our methods. So we can test each of the methods separately by pressing the corresponding button. The first button "addMarkers" places all markers back to the map and we can start from the beginning again.

First we take a look at the removeOverlay and removeAllOverlays method from the IWOverlayLayer class. We start with the second button removeOverlay which invokes the following method call:

map.getOverlayManager().getLayer(0).removeOverlay(marker2);

In this case the marker2 should be removed. If you press the third button removeAllOverlays the following statement is called:

map.getOverlayManager().getLayer(1).removeAllOverlays();

In this case all markers on layer 1 should be removed.

Now we take a look at the removeLayer and removeAllLayers method from the IWOverlayManager class. The fourth button removeLayer removes a layer with all of his overlays from the map. In our example the markers6 and marker7 should be removed.

map.getOverlayManager().removeLayer(2);

Finally the last button removeAllLayers makes a call to the following statement which removes all layers with their overlays from our map.

map.getOverlayManager().removeAllOverlays();

« Previous chapter 5: Controls Back to Index Next chapter 7: Shapes and Layers »