« Previous Chapter 10: Drawing with SVG and VM    Back to Index    Next Chapter 12: GeometryFilter »

Chapter 11: SelectionAPI

The SelectionAPI provides functions to select areas on a map and display them graphically.

It is based on an IWMap, which represents the basic map and provides the basic functionalities such as pan, zoom. The areas to be selected (for example, zip code areas) are represented by the base layer. The selected areas are displayed in an overlying layer. There is also the possibility of additional layers. Base layer, selection layer and additional layers can be filtered geographical and/or by their attribute values with their own rendering options.

When selecting a new base layer all selections and associated layers are reset.

11.1 Load API

To use the SelectionAPI, the integration of the MapAPI-1.1 is necessary. The following code snippet shows how such integration can be performed on an HTML page:

<script type="text/javascript" src=http://iw.mapandroute.de/MapAPI-1.1/js/core.js"></script>
This provides the basic functionalities of MapAPI. The requiered functions for the SelectionAPI, are located in the module 'selection'. These can be loaded with the following code snippet:
IWLoader.loadModules(['selection']);
The following steps should only be performed when the modules are fully loaded. For this purpose the MapAPI provides an event 'onmoduleload' , which is called when the requested modules have been loaded.
IWEventManager.addListener(IWLoader, 'onmoduleload', function(event) { 
	if (event.name == 'selection') { 
		//now you can use the SelectionAPI
	}
}); 

Please remember to declare the listener before loading the modules!

11.2 SelectionManager

For the SelectionAPI there are special layers, which can be accessed via the IWSelectionManager. When initializing the IWSelectionManager these layers are loaded and are available after initialization. For this purpose, the IWSelectionManager trigger the event 'oninitialize' , in which the existing layers are included. Each layer in turn contains a 'layerName' and a 'layerId'. The name is used to display. The ID is used to identify the layer and is an input parameter in many functions of the SelectionAPI. Here is a code snippet:

//initialize selectionManager			
selectionManager = new IWSelectionManager();
IWEventManager.addListener(selectionManager, 'oninitialize', function(event)
{
  var layers = event.layers;
  for(var i=0; i<layers.length; i++) {
    // Zugriff auf layers[i].layerId
    // und layers[i].layerName
  }
});

Alternatively to the attribute 'layers' in the event object, the available layers can be retrieved with the method selectionManager.getLayers() and can be displayed in a list.

Initialize the selection

The basis of a selection is a IWMap , that can be initialized using the standard methods of the MapAPI-1.1

map = new IWMap(mapContainer);
map.setCenter(coord, zoomLevel, maptype);

The central object of SelectionAPI is the IWSelectableMap . This provides a container for underlying IWMap , the baselayer, the selectionlayer and the additional layers. By alteration of rendering options the appearance of the layers can be customized. Here is an example how a IWSelectableMap can be initialized:

selectableMap = new IWSelectableMap(map);

If IWSelectableMap is initialized you can set the layer which you want to use for selecting.

selectableMap.setLayer(layerId, area, filters, baseLayerRenderOptions, highlightRenderOptions, selectionRenderOptions);
Name Description
layerIdId of the layer to select
area Limiting the shown geometries to the given area.
  • bounding box: {topleft: "697526,6759257", bottomright: "789250,6667533"}
  • circle: {coord: "726113,6702540", radius: 16758}
  • polygon: {polygon: ["727641,6713853","739566,6726694","749197,6708808"]}
filters Limiting the shown geometries with the given filter.
  • prefix: {type: "prefix", key: "PLZ", value: "5"} a prefix filter to select only postal codes starting with 5
  • value: {type: "value", key: "PLZ", value: "53175"} a value filter to select only postal code 53175
baseLayerRenderOptionsRenderOptions for baselayer
highlightRenderOptionsRenderOptions for highlighting (mouseover)
selectionRenderOptionsRenderOptions for selectionlayer

If the layer is set, the event 'onlayerchanged' is thrown. To respond to changes in the selection, another listener must be defined in the listener of this event which respond to the event 'onselectionchange'. Here is the list of the selected elements are accessed

IWEventManager.addListener(selectableMap, 'onlayerchanged', function(event)
{
  selectionchangeListener = IWEventManager.addListener(selectableMap,
   'onselectionchange', function(event)
   {
     showSelectedItems(event.selectedItems);
   });
});

Start of selection

Starting the selection means that the map is initialized, a base layer was selected and now the elements of this base layer can be selected on the map. How a selection is performed depends on the one hand by the "tool" (point, circle, polygon, ID) and on the other hand by the "mode".

Mode

The mode determines how the selected elements should be included in the current selection. The different modes are defined as constants in the IWSelectionMode class.

Name Description
NONE no selection possible
ADD adds the selected items to the current selection
REMOVE deletes the selected items from the current selection
TOGGLE changes the selection state of the selected elements
EXCLUSIV moves the selection exclusively on selected items
UNSELECTALL deletes all selected items from the current selection

Tools

Point

Allows the selection by clicking on elements of the base layer. The element which includes the corresponding coordinate is now added or removed from the current selection.

selectableMap.selectByCoordinate(selectionMode);

Circle

By clicking and dragging on the map a circle is spanned that selects all the elements that intersect this circle.

selectableMap.selectByCircle(selectionMode);

Polygon

With several clicks on the map a polygon is spanned that selects all the elements that intersect this polygon.

selectableMap.selectByPolygon(selectionMode);

ID

The elements of a selection layer consist of at least an ID and a name. The ID can be used to add or remove elements in/from the selection, without the graphical support at the map. For this, the following method can be used:

selectableMap.selectById(id, selectionMode);

The parameter id can be a comma-separated list of ids to select more than one ID.

finish selection

If the selection should be stopped, the method disableSelect() can be called, whereby the standard functions of the map (move, zoom, ..) are restored.

selectableMap.disableSelect();

Additional layers

To draw additional layers on the map, with the features of filter and renderoptions, you can use the function drawLayer. The following exmaple draw the postalcode area 53175 with a blue border on the map
var filters = [{type:'value',key:'ID',value:'53175'}];
selectableMap.drawLayer('PLZ', null, filters, {"fill": "red", "fillOpacity":0, "stroke": "blue", "strokeWidth": 8}, null); 

RenderOptions

Essentially the selectableMap consists of layers which can be customized in its presentation with the following rendering options:

Property Description Value
fill the fill or text color CSS color description, e.g. #ff0000 or blue or rgb, such as rgb(0,0,0,0)
fillOpacity the opacity of the fill color value between 0 (transparent) 1 (opaque)
stroke the stroke color CSS color description, e.g. #ff0000 or blue
strokeWidth the width of the stroke in pixels number

The following methods can set new rendering options for base layer, the selection and the highlighting (mouseOver), which are passed as JSON objects:

var renderOptions = JSON.parse('{"fill": "red",	"fillOpacity":0.5, "stroke": "0/0/0", "strokeWidth": 10}'); 
selectableMap.setRenderOptions(renderOptions); 
selectableMap.setBaseLayerRenderOptions(baseLayerRenderOptions);
selectableMap.setHighlightingRenderOptions(highlightingRenderOptions);

Events

Events are thrown by the API to notify the client that initializations or changes are completed. These events must be intercepted by appropriate Listener. For this purpose, the method addListener of IWEventManager can be used (more on this in the documentation of MapAPI).

Certain functionalities are only available when the corresponding event was received. For example, the available layer will only be requested if the SelectionManager has been initialized.

IWLoader

onmoduleload

Informs the client that the requested modules from the MapAPI modules are fully loaded. For the SelectionAPI the modules 'graphics' and 'selection' are required:
IWLoader.loadModules(['graphics','selection']);

The listener can be defined as follows:

IWEventManager.addListener(IWLoader, 'onmoduleload', function(event) { 
	if(event.name == 'selection') {
		...
	} 
}); 

IWSelectionManager

oninitialize

Informs the client that the manager was initialized after new IWSelectionManager() is called. After that, the layers are available.

IWEventManager.addListener(selectionManager, 'oninitialize', function (event) { 
	var layers = event.layers; //weitere Verarbeitung 
});

In the attribute 'layers' this event provides an array with the existing base layers. Each object in this array has the following attributes:
Name Description
layerId Id of the layer
layerName Name of the layer to display

IWSelectableMap

onlayerchanged

Is thrown if a new layer is selected. This can be done via the method selectableMap.setLayers() :

IWEventManager.addListener(selectableMap, 'onlayerchanged', function(event){ //selection can be started });  
selectableMap.setLayer(layerId, area, filters, baseLayerRenderOptions, highlightingRenderOptions, selectionRenderOptions); 

The baselayer is now fully initialized and the selection can be started.

onselectionchanged

is thrown when the selection has changed.

IWEventManager.addListener(selectableMap, 'onselectionchange', function(event) {
showSelectedItems(event.selectedItems); }); 

The event includes the attribute selectedItems, which contains a list of all selected elements. Each item has the following attributes:

Name Description
itemId Id of the element
itemName Name of the element to display

   « Previous Chapter 10: Drawing with SVG and VM    Back to Index    Next Chapter 12: GeometryFilter »