Using a GeoMap inside your application is very straightforward; you just have to instantiate the sap.ui.vbm.GeoMap Control. It is also available in declarative style of Views. Without any further settings, the Visual Business GeoMap control comes up with the predefined default size of 800x600 pixels with map data from MapQuest.

JS Views

var oVBI = new sap.ui.vbm.GeoMap();
    

XML View

<View xmlns="sap.ui.core.mvc" xmlns:vbm="sap.ui.vbm">	
   <vbm:GeoMap />
</View>
    

For different control sizes, you can use the properties width and height. You can provide absolute sizes in pixels or relative sizes in percent. In the later case it is important to size the parent elements properly otherwise the map has the size 0x0!

To add visual content to your Map, Visual Business provides the abstraction of Visual Objects. These could be thought of as symbols representing a datapoint in your model. Several simple Visual Objects are currently available.

• Spot
• Area
• Route
• GeoCircle/Circle
• UI5 Control Container

These are usually only defined by properties such as their color, size and their respective geospatial coordinates. There are also more complex Visual Objects available. A Spot for example can include a picture that should be rendered. A Container needs a UI5 Control that is supposed to be rendered instead.

The most common VO for highlighting a position is a Spot. In the simplest form you just need to provide the geo position in the format lon;lat;0. The Spot is based on a image. There are some pre-defined Spot images delivered with the control. They can be addressed with the Spot property type. Possible types are defined by enumeration sap.ui.vbm.SemanticType and the default type (Default) selects a blue pin with a neutral status icon.

Here is the code for JavaScript Views in UI5:

var oVBI = new sap.ui.vbm.GeoMap({
   vos : [ new sap.ui.vbm.Spots({	
      items : [ new sap.ui.vbm.Spot({ position : "20;0;0" }) ]
   }) ]
});
    

By providing the type property you can change the look of the Spots in a pre-defined way. The Spots vary in color and size for each of the semantic types. Additionally, the status icon changes accordingly.

Here is the code for JavaScript Views in UI5:

var oVBI = new sap.ui.vbm.GeoMap({
   vos : [ new sap.ui.vbm.Spots({	
      items : [ new sap.ui.vbm.Spot({ type : "Error", 
                                      position : "-20;0;0" }),
                new sap.ui.vbm.Spot({ type : "Success", 
                                      position : "20;0;0" }) 
              ]
   }) ]
});
    

The Spot also supports a text property. The default visualization is suitabled for numbers with up to 5 digits given as text. If this is not sufficient, you may shorten the numbers, for example 1.000.000 = 1M.

Here is the code for JavaScript Views in UI5:

var oVBI = new sap.ui.vbm.GeoMap({
   vos : [ new sap.ui.vbm.Spots({	
      items : [ new sap.ui.vbm.Spot({ type : "Error", 
                                      text : "5", 
                                      position : "-20;0;0" }),
                new sap.ui.vbm.Spot({ type : "Success",
                                      text : "32678", 
                                      position : "20;0;0" }) 
              ]
   }) ]
});
    

Route and Area objects are considered more complex objects. In this section, we demonstrate how to create them.
The format for the Route geo coordinates is:

position: 'lon(0);lat(0);z(0);lon(1);lat(1);z(1);...lon(n);lat(n);z(n)'

where lon(n) is Longitude and lat(n) is Latitude. z(n) is the height coordinate, which currently should be set to 0. The arrows of the Route show the direction of it, and are given with the start and end parameters, with values 0 (disable) or 1 (enable). So, when the start has 0 and the end 1, the start of the Route will not have an arrow; only the end will, thus showing the direction of the route.
The format for the Area geo coordinates is the same as for the Route, the only difference being that the first and the last coordinate are connected to form a closed and filled Area.

Notes:
- The color parameter defines the fill color of the objects.
- The tooltip is used in the following code just to have some action and information while hovering over the objects.

Here is the code for JavaScript Views in UI5:

var oVBI = new sap.ui.vbm.GeoMap({
   vos : [ 
      new sap.ui.vbm.Routes({ 
         items : [ 
            new sap.ui.vbm.Route({ 
               position: '-10;30;0;30;-20;0;40;10;0', 
               start: "0", 
               end: "1",
               color: 'rgb(92, 186, 230)', 
               tooltip: 'This is a Route' 
            })
	   ]}),
      new sap.ui.vbm.Areas({ 
         items : [ 
            new sap.ui.vbm.Area({ 
               position: '-65;10;0;-55;-30;0;-40;-10;0',
               color: 'rgba(217, 152, 203, 0.7)',
               tooltip: 'This is an Area'
		   })
     ]})
   ]
});
	    

Container objects allow to place arbitrary SAPUI5 controls on top of the map at a given geo-position. The default alignment for the container is centered at the given position. Other aligments are also supported. The container itself is fully transparent. In case you need a colored background you may add a style class with your own CSS to the hosted control with the addStyleClass() function.

Here is the code for JavaScript Views in UI5:

var oVBI = new sap.ui.vbm.GeoMap({
   vos : [ 
      new sap.ui.vbm.Containers({ 
         items : [ 
            new sap.ui.vbm.Container({ 
               position: '15;15;0', 
               item:
      //Container content          
      new sap.suite.ui.microchart.HarveyBallMicroChart({
         size: "S",
         total: 100,
         totalScale:"Mrd",
         showTotal: false,
         items: [ 
         new sap.suite.ui.microchart.HarveyBallMicroChartItem({
            fraction: 63,
            fractionScale: "Mrd",
            color: "Good"
         })]
      })
      //End content   
            })
         ]})
   ]
});
	    

In addition to the semantically-typed Spot with a built-in visualization, you can use any image for a Spot. The image needs to be loaded as a resource and can be referenced by Spots. Since the Spot was built for images like pins, the image is, by default, aligned in a way that the bottom center of the image is at the given geo position. For other images, a center alignment might be more appropriate.

Here is the code for JavaScript Views in UI5:

var oVBI = new sap.ui.vbm.GeoMap({
   resources     : [
      new sap.ui.vbm.Resource({ "name" : "SAP_logo",
                                "src"  : "images/SAP_logo.png"}) 
   ],
   vos : [ new sap.ui.vbm.Spots({
      items : [ new sap.ui.vbm.Spot({ position : "20;0;0",
                                      tooltip  : 'SAP',
                                      image    : "SAP_logo",
                                      scale    : "0.2;0.2;0.2",
                                      alignment: "0"}) 
      ]
   })]
});
    

The map control provides the properties centerPosition add zoomlevel. They can be used to set the focus on particular region.
It is also possible to set the map view programatically later on using those properties. Further the control provides function zoomToGeoPosition(), which takes one or more positions to be centered and the desired zoomlevel.

Here is the code for JavaScript Views in UI5:

var oVBI = new sap.ui.vbm.GeoMap({
	centerPosition: "-122.81;49.14",
	zoomlevel: 9
});
    

To enable interaction with the Spots you create, the GeoMap control enables the registration of event handlers automatically. For the purpose of a right-click on the element or a long press on touch devices, it will fire a contextMenu event. The object firing the event is the context of the event handler; this gives you direct access to all its data. In the event parameters, you'll find a ready-made instance of sap.ui.unifier.Menu for adding your menu items.

Here is the code for JavaScript Views in UI5:

var oVBI = new sap.ui.vbm.GeoMap({
   vos: [ new sap.ui.vbm.Spots({
      items: [
         new sap.ui.vbm.Spot("DemoSpot", {
            position: "20;0;0",
            contextMenu: function(oEvent) {
               var activeSpot = this.getId();
               var oMenu = oEvent.mParameters.menu;
               oMenu.addItem(new sap.ui.unified.MenuItem({
                  text: "Context menu for " + activeSpot
               }));
               this.openContextMenu(oMenu);
            }
         })
      ]
   })]
});
    

Here, we use Spot VOs to demonstrate a Click event. When you left-click (tap) a spot, an alert shows the appropriate Spot ID. Again, the context of the event handler is the object firing the event. Thus, we can directly access the object data, e.g. its text property as in the sample.

Here is the code for JavaScript Views in UI5:

function onClick( oEvent ) {
   alert( "onClick " + this.getText() );
};
var oVBI = new sap.ui.vbm.GeoMap({
   vos : [ new sap.ui.vbm.Spots( {
      items : [ 
         new sap.ui.vbm.Spot( { type : "Error", 
                                text : "1", 
                                position : "20;0;0",
                                click: onClick }),
         new sap.ui.vbm.Spot( { text: "2",
                                position : "20;20;0",
                                click: onClick })
      ]
   })]
});
	    

CenterChanged is an event which is fired when we move the map using left-click and drag (or tap and drag). In addition to the centerpoint coordinates, the event also provides the current zoomlevel and the bounding box for the visible map part viewportBB.
All this information allows applications to keep track of the current display and may be used to load data on demand to limit the number of objects on the map to the visible ones.
The example updates the centerPoint display shown below the map while we move the map around.

Here is the code for JavaScript Views in UI5:

function onCenterChanged( oEvent ) {
   var aCp = oEvent.getParameter( "centerPoint" ).split(";");
   centerDisplay.innerText = "centerPoint X: " + 
      Number(aCp[0]).toFixed(3) + ", Y: " + 
      Number(aCp[1]).toFixed(3);
};
var oVBI = new sap.ui.vbm.GeoMap({
   centerChanged: onCenterChanged
});
	    

Move the map to show values here

ZoomChanged is an event which is fired when we zoom the map using the mouse wheel, pinch gesture, navigation control, or keyboard +/-. Besides the zoomLevel, the event also provides the new centerPoint and the bounding box for the visible map part viewportBB.
All this information allows applications to keep track of the current display and may be used to load data on demand. Thus, it is possible to refine data points on higher zoomlevels and even to change to visualization, e.g. from areas to single points.
This example updates the zoomLevel display shown below the map while we zoom the map.

Here is the code for JavaScript Views in UI5:

function onZoomChanged( oEvent ) {
	var level = oEvent.getParameter( "zoomLevel" );
	zoomDisplay.innerText = "zoomLevel: " + level; 
};
var oVBI = new sap.ui.vbm.GeoMap({
   zoomChanged: onZoomChanged
});
	    

Zoom the map to show values here

When we want to control the selection of objects, we can use the select and deselect events on the VO aggregation. The events are always fired in the sequence deselect - select. Each event provides the list of affected VOs as event parameter.
For each VO aggregation you can set properties minSel and maxSel to define the selection cardinality to control how objects can be selected. Property minSel can be 0 (can be deselected) or 1 (cannot be deselected). Property maxSel can be 0 (no selection allowed at all), 1 (only one can be selected) and n (all can be selected).
Left-clicking (tapping) selects an object. Holding down Ctrl-key while clicking toggles the selection. Pressing Shift-key while clicking adds the object to the selection (if possible by the defined selection params). Left-clicking on an object that's not selected first deselects all other selected objects in the group, and then selects the object itself. For selecting/deselecting multiple VOs at once you can switch to the rectangular selection mode by pressing key r.
Note: When maxSel is 0, minSel must be 0 as well!

Here is the code for JavaScript Views in UI5:

function onSelect( oEvent ) {
   alert( oEvent.getParameter("selected").length + 
                                  " VOs selected" );
};
function onDeselect( oEvent ) {
   alert( oEvent.getParameter("deselected").length + 
                                  " VOs deselected" );
};
var oVBI = new sap.ui.vbm.GeoMap({
   vos : [ new sap.ui.vbm.Spots( {
      minSel: "0",	
      maxSel: "n",	
      select: onSelect,
      deselect: onDeselect,
      items: [ 
         new sap.ui.vbm.Spot( { 
            type : "Error", 
            text : "123", 
            position : "20;0;0",
            selectColor: 'RHLSA(0;1.0;1.5;1.0)' }),
         new sap.ui.vbm.Spot( { 
            type : "Warning", 
            position : "20;20;0",
            selectColor: 'RHLSA(0;1.0;1.5;1.0)' })
      ]
   })]
});
	    

Detail windows can be used to show more information and allow extended interaction with a VO. On the click event we call the openDetailWindow function with a caption parameter to trigger the opening. Before the window is actually opened, the GeoMap control fires the openWindow event in which we implement the content and logic for our detail window. We suggest that you register the openWindow event just once and on demand and to give the VO as context by passing it as a listener. Finally, you may consider destroying the content on event closeWindow to avoid memory leaks. However, by adding optional parameter only when calling placeAt, this may not be necessary.
Since the dialog window layout uses UI5 controls, please have a look at the appropriate UI5 control tutorials for an explanation on how each is used. This is just an example to show how to open a dialog window on a Visual Business control.
Note: openDetailWindow function with just a caption parameter, opens a detail window at the VO anchor coordinate (or at the point of click for some objects such as the GeoCircle). If a different position is required, the format is openDetailWindow( caption, x, y ) where the x and y coordinates are offsets from the VO anchor point.

Here is the code for JavaScript Views in UI5:

function onClick( oEvent ) {
   this.openDetailWindow(this.getType() + " spot details");
   //register openWindow event with the VO as context
   var oMap = this.getParent().getParent(); 
   oMap.attachEventOnce("openWindow", onOpenDetail, this);
};
var oForm = null;
function onOpenDetail( oEvent ) {
   //create some window content
   if (!oForm) {
      oForm = new sap.ui.layout.form.SimpleForm({
         maxContainerCols: 1,
         width: "200px",
         labelMinWidth: 50,
         content: [
            new sap.m.Label({
               text:"Position"
            }),
            new sap.m.Text({
               text:this.getPosition()
            })
         ]
      });
   }
   //place the window content
   oForm.placeAt(oEvent.getParameter("contentarea").id,'only');
};
var oVBI = new sap.ui.vbm.GeoMap({
   vos : [ new sap.ui.vbm.Spots({
      items : [ new sap.ui.vbm.Spot( {
         type : "Error", 
         text : "123", 
         position : "-30;0;0",
         click: onClick
      })]
   })]
});