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

Source code example 6a:


<!DOCTYPE html>

<html>
	<head>		
		<title>Chapter 6: Overlays example 6a</title>
		<script type="text/javascript" src="http://iw.mapandroute.de/MapAPI-1.1/js/core.js?vnr=0&pnr=0"></script>
		
		<script type="text/javascript">
		
			function initialize()
			{
				var map = new IWMap(document.getElementById('map'));

				var icon = new IWIcon('../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 icon = new IWIcon('../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.

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.

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

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

Source code example 6b:

<!DOCTYPE html>
<html>
	<head>		
		<title>Chapter 6: Overlays example 6b</title>
		<script type="text/javascript" src="http://iw.mapandroute.de/MapAPI-1.1/js/core.js?vnr=0&pnr=0"></script>
		
		<script type="text/javascript">
		
		function initialize()
		{
			var map = new IWMap(document.getElementById('map'));
			
			//define icons
			var icon = new IWIcon('../img/symbols/house/house_red_30.gif', new IWPoint(15, 13), new IWSize(30, 26));  
			var icon_marker = new IWScaleDependentIcon('../img/symbols/marker.png', new IWPoint(8, 8), new IWSize(16, 16), new IWRange(10, 13));
			   
			//set marker
			var marker = new IWMarker(map, new IWCoordinate(7.1408879, 50.70150837, IWCoordinate.WGS84).toMercator());				
			marker.setDefaultIcon(icon);
			marker.addScaleDependentIcon(icon_marker);
			
			//set visibility
			map.getOverlayManager().getLayer(0).setVisibilityRange(new IWRange(10, 19));
			
			IWEventManager.addListener(map, 'oninitialize',
				function()
				{
					map.getOverlayManager().getLayer(0).addOverlay(marker);
				}
			);

			IWEventManager.addListener(IWLoader, 'onmoduleload', function(event)
			{
				if (event.name == 'controls') {
					map.getLayoutManager().getLayer(0).addControl(new IWSliderControl(map), IWAlignment.RIGHT, IWAlignment.BOTTOM, 0, 0);
					map.setCenter(new IWCoordinate(7.1408879, 50.70150837, IWCoordinate.WGS84));
				}
			});
			
			IWLoader.loadModules(['controls']);
		}
			
		</script>	
	</head>
	
	<body onload="initialize();" class="tutorial">
		<div id="map" style="background-color: #dddddd; width: 450px; height: 300px"></div>
	</body>
</html>

Here we add a new marker icon which is shown scale dependent

marker.addScaleDependentIcon(icon_marker);

We can add different IWScaleDependentIcons for different scale levels. In this example we are using another icon for higher scales. The icon_marker in this example is shown if the map has a zoomlevel between 10 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.

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

Source code example 6c:

<!DOCTYPE html>
<html>
  <head>
	<title>Chapter 6: Overlays example 6c</title>
	<script type="text/javascript" src="http://iw.mapandroute.de/MapAPI-1.1/js/core.js?vnr=0&pnr=0"></script>
    <script type="text/javascript">

			function initialize()
			{
				var map = new IWMap(document.getElementById('divMap'));

				IWEventManager.addListener(map, 'oninitialize',
					function(e)
					{
						// Create marker
						var icon = new IWIcon('../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);

						//open tooltip on mouseover
						IWEventManager.addListener(marker, 'onmouseover',
							function(e)
							{
								map.openTooltip(this.getCoordinate(), 'infoware GmbH');
								var listener = IWEventManager.addListener(marker.getContainer(), 'onmouseout',
									function(e)
									{
										map.removeTooltip();
										IWEventManager.removeListener(listener);
									}.iwclosure(this)
								);	      					
							}.iwclosure(marker)
						);

						// open infoballoon on click
						IWEventManager.addListener(marker, 'onclick',
							function(e)
							{
								map.removeTooltip();
								map.openInfoBalloon(this.getCoordinate(), '<b>infoware GmbH</b><br/><p>Riemenschneiderstr. 11<br/>53175 Bonn</p>');
							}.iwclosure(marker)
						);

						//add marker to map
						var overlayLayer = map.getOverlayManager().getLayer(0);
						overlayLayer.addOverlay(marker);
					}
				);
	  			
				map.setCenter(new IWCoordinate(7.1408879, 50.70150837, IWCoordinate.WGS84));
    	}
		</script>
  </head>
  <body onload="initialize();" class="tutorial">
    <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(marker, 'onmouseover',
	function(e)
	{
		map.openTooltip(this.getCoordinate(), 'infoware GmbH');
		var listener = IWEventManager.addListener(marker.getContainer(), 'onmouseout',
			function(e)
			{
		  		map.removeTooltip();
		   		IWEventManager.removeListener(listener);
		 	}.iwclosure(this)
		);	      					
	}.iwclosure(marker));

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(marker, 'onclick',
	function(e)
	{
		map.removeTooltip();
		map.openInfoBalloon(this.getCoordinate(), ' <b>infoware GmbH</b><br/><p>Riemenschneiderstr. 11<br/>53175 Bonn</p> ');
	}.iwclosure(marker));

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 Using labeled markers

The above exmple allows you to customize the behavior and icon of the image. But imagine a set of markers which have the same icon except a number or letter symbolizing the index in a hit list. For 100 hits in the list, you would have to provide 100 individual icons...

An easier way is to to use labels on your markers. A label is a short text (e.g. a number) which can be displayed on top of the image. This may be provided either by an additional and optional parameter to IWMarker, or by calling IWMarker.setLabel().

Overlay labeled markers example

Source code for labeled markers example:

With a additional parameter in IWMarker we can set a label for each marker.


		var coords = [
			new IWCoordinate(794946, 6567896),
			new IWCoordinate(795149, 6567920),
			new IWCoordinate(795674, 6568342),
			new IWCoordinate(795901, 6568596),
			new IWCoordinate(796185, 6568818),
			new IWCoordinate(795787, 6569231),
			new IWCoordinate(795369, 6569549),
			new IWCoordinate(794881, 6569219),
			new IWCoordinate(794635, 6569207),
			new IWCoordinate(794272, 6568975)
		];
		
		var url = iwconst.GLOBAL_APP_URL + 'img/symbols/marker.png';
		var icon = new IWIcon(url, new IWPoint(16, 16), new IWSize(32, 32));
		
		var layer = map.getOverlayManager().getLayer(0);
		for (var i = 0; i < coords.length; i++)
		{
			var marker = new IWMarker(map, coords[i], (i + 1));
			marker.setDefaultIcon(icon);
			layer.addOverlay(marker);
		}

6.5 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.

Creating your own overlay example

Source code for creating your own overlay example:

<script type="text/javascript">

			function MyMarker(map, coordinate)
			{
				IWOverlay.call(this, map, coordinate);
				this.setDraggable(true);
				
				var container = this.getContainer();
				//put something in this container, e.g an image
				//...
			}
			
			MyMarker.prototype = new IWOverlay();
			
			function initialize()
			{
				var map = new IWMap(document.getElementById('map'));
				var myMarker = new MyMarker(map, new IWCoordinate(7.141579, 50.701750, IWCoordinate.WGS84).toMercator());
				
				//add listener, etc.
				//...
			}
		</script>

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

IWOverlay.call(this, map, coordinate);

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 by calling 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.

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.6 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:

Removing overlays example

Source code for removing overlays example:

function removeSingleOverlayExample()
{
	map.getOverlayManager().getLayer(0).removeOverlay(marker1);
}

removes overlay marker1 from layer 0

function removeAllOverlaysExample()
{
	map.getOverlayManager().getLayer(0).removeAllOverlays();
}

removes all markers from layer 0. Markers in layer 1 are still visible

function removeLayerExample()
{
	map.getOverlayManager().removeLayer(1);
}

removes layer 1 (with all overlays)

function removeAllLayersExample()
{
	map.getOverlayManager().removeAllLayers();
}

removes all layers

« Previous Chapter 5: Controls Back to Index Next Chapter 7: Shapes »