5.13.5.1 Customizing Maps

 



Overview

 

A network map is a graphical and hierarchical representation of the network. It allows you to represent network elements and the logical relationship between them in a simple manner. Map objects in the web client are represented as map symbols. The map symbols are displayed in different colors to convey the status of the network element at that given point. Similar to the Java client, the web client map interface has powerful features with the map toolbar for performing map viewing and relayout operations, and the right click menu options for manipulating the map symbols.

 

The map elements on the map are dynamically updated with all managed device information without the need for refreshing the map UI.

 

The Web client offers many options to customize both the look and feel, as well as the functionality associated with network maps. This topic deals with customizing the map module of the web client.


Files Involved in Map Module

 

File Name File Location

Description

map-struts-config.xml

webclient/map/conf/

The struts configuration file for Map.

map-tiles-defs.xml

The tiles definition file for Map.

map-validation.xml

The validation file for Map.

map-validator-rules.xml

The validator rules file for Map.

mapwebclientconfig.xml

 

Specifies the icons and the status images used when showing a map symbol on the map and in its details form

mapwebclientconfig.dtd

The DTD for the above file

maptooltip.xml

Specifies the tooltip for the map symbol and map link.

maptoolbar.xml

 

users/<username>/

Specifies the icons and action commands to be used in the web client map toolbar.

maptoolbar.dtd

The DTD for the above file.

addMapHeader.jsp

webclient/map/jsp/

 

Renders the Map Header.

mapView.jsp

Displays the rendered map.

GMapBody.jsp

Renders the Google Map.

NmsMap.js

webclient/map/js

The main file where the initial control from mapView.jsp is routed.

MapMemory.js

Script files holding all the methods for storing , retrieving map, symbols and link properties.

MapManager.js

The controller file which calls the layout and renderer methods for the map.

MapEventHandler.js

The file that handles all the map related methods.

MapToolbar.js

The file that handles the toolbar rendering.

MapMenu.js

The file that handles creation of map menus.

MapUtil.js

The utility methods and Modal Box html contents for the maps are present in this file.

 

 

  1.  

    Note: WebNMS Maps is built using Dojo Toolkit. Dojo Toolkit has large number of modules and plugins for building rich web applications. We are currently using Dojo's Graphics and Context menu related modules in Maps. You can refer to the Dojo Toolkit website for basics graphic rendering and module creation tutorials.

     

    Scalable Vector Graphics (SVG):

    Dojo graphics uses SVG, which is the xml based language for creating graphics in web browser, as the main source of graphics rendering. SVG is highly recommended for interactive map visualizations.

     

 

Scalable Vector Graphics - Concepts and Terms:

The surface object is the main SVG board where all the shapes are rendered. It is similar to the paper board for drawing.  The RootGroup is the main group which contains all the symbols and link as its children. The RootGroup is used for the purpose of zooming map. When zooming takes place , this RootGfxGroup is zoomed visually showing zoom effect.

Each symbol component here is represented as SVG Group, which holds some 'n' number of shapes in it. You can create as many shape you want and group it.

 

GfxGroup Represents SVG Group object which have shapes as its children.
GfxShape Array of shapes represent symbol or link.
MapMemory Storing of SVG Groups and Shapes.

 

 

_mapSymGroup { SymbolName : SVGGroup object of symbol }
_mapSymShape { SVGGroup Id : [ Shape Array of the symbols }
_mapLinkGroup { LinkName : SVGGroup object of link }
_mapLinkShapes { SVGGroup Id : [ Shape Array of the links }


 

Web Client Map Architecture


 

 

 

Fig 1  : WebClient Map Architecture

 

 

The layouts and the renderers are responsible for the arrangement of the map symbols and the look and feel of the map interface. There are 5 default implementations for the map layouts, and 4 default implementation for symbol rendering.  The script files for layout and rendering are available in the <WebNMS Home>/webclien/map/js folder. You can write your own layout and renderer classes based on your requirement.

 

The map symbol's right click menu provides options to perform map related operations. Various view operations are possible using these menus. The right click menu can be customized by modifying the menu files present in the <WebNMS Home>/mapdata/menus/  folder. The map toolbar can be customized by modifying the maptoolbar.xml file present in the <WebNMS Home>/users/<username> location.

 

 

 

 

Customizing the Look and Feel of the Map

 

The look and feel of the map module includes the background image, icons, menus, and the toolbar. The way to customize them are discussed below.

 

Customizing the Background Image

 

The background image of the map can be set by providing the image name for the imageName property when creating the map in the map filter.  The image must be present in the <WebNMS Home>/webclient/map/images folder.



Customizing the Icons

The icon files mapping for the map symbols must be provided in the mapwebclientconfig.xml file present in the WebNMS Home>/webclient/map/conf/ folder. Set of severity images for every type of device. The image file must be present in the <WebNMS Home>/webclient/map/images folder.

 

    1. <type-config type="switch" >

      <map-view>

      <icon-config status="default" imageName="/webclient/map/images/switch_icon.png"/>

      </map-view>

      <symbol-details>

      <icon-config status="Clear" imageName="/webclient/map/images/switch_sev_clear.gif"/>

      <icon-config status="Major" imageName="/webclient/map/images/switch_sev_major.gif"/>

      <icon-config status="Minor" imageName="/webclient/map/images/switch_sev_minor.gif"/>

      <icon-config status="Warning" imageName="/webclient/map/images/switch_sev_warn.gif"/>

      <icon-config status="Critical" imageName="/webclient/map/images/switch_sev_critical.gif"/>

      <icon-config status="Unknown" imageName="/webclient/map/images/switch_sev_unknown.gif"/>

      </symbol-details>

      </type-config>

 

Customizing the Menus

 

The menu options can be customized in the menu files available in the <WebNMS Home>/mapdata/menus folder. The menu files for the web client will be present within the <HTML-UI> tag.

 

Two action types are supported for the map menus, the "function" and "URL". Any action-type other than function is considered a open link (URL) type.


Sample entry from <WebNMS Home>/mapdata/menus/objectsmenu.xml

    1. //function type

       

      <HTML-UI action_type="function" action_value="showSymbolProperties"/>

       

      //URL type

       

      <HTML-UI action_type="_top" action_value="/topo/objectdetails.do?name=${objName}&amp;selectedTab=Network Database&amp;type=${type}&amp;menu=listmenus&amp;requestid=SNAPSHOT"/>

       

The function implementation is available in the SymbolMenuActions.js present in <WebNMS Home>/webclient/map/js file.

    1.  

      var showSymbolProperties = function( _mapObjectName, value , menuRef){

      var _mapObjectProps = mapMemory.getSymbolProperties(_mapObjectName) || mapMemory.getLinkProperties(_mapObjectName);

      var _mapObjectType = _mapObjectProps['DISCRIMINATOR'] || _mapObjectProps['type'];

       

      if( _mapObjectType === 'MapSymbol' || _mapObjectType === 'MapGroup' || _mapObjectType === 'MapContainer' || _mapObjectType === 'symbol' || _mapObjectType === 'group' || _mapObjectType === 'container' ){

      _symbolPropertiesModalBox(_mapObjectName , value, menuRef);

      }else if( _mapObjectType === 'MapLink' || _mapObjectType === 'link'){

      _linkPropertiesModalBOX( _mapObjectName, value, menuRef);

      }

      }

       

 

Customizing the Toolbar

 

The map toolbar buttons are defined in the <WebNMS Home>/users/<username>/maptoolbar.xml file. The property setting client="HTML" distinguishes the web client map toolbar entries.  You can add your own action_command implementation to include a button in the toolbar.


Sample toolbar entry provided below:

    1. <TOOLBAR-BUTTON action_command="MoveButtonAction" client="HTML" enabledimage="/webclient/map/images/edit_icon.png" iconName="/webclient/map/images/edit_icon.png" name="edit" tooltip="Edit"/>

The implementation for the action_command entries is handled in the <WebNMS Home>\webclient\map\js\MapToolbarAction.js file. For the above entry, the action command "MoveButtonAction" implementation is handled in the MapToolbarAction.js file.

To include a new button in the toolbar, you need to include a funtion in the MapToolbarAction.js file, and map the value in the maptoolbar.xml file. You can refer to the MapToolbarAction.js file to write your own implementation for handling the action.

 

Customizing the Map Display

 

The MapViewAction is the action class used to return the specified map view to be displayed using mapView.jsp. This mapping is specified in map-struts-config.xml as shown below.

    1. <action path="/MapView" type="com.adventnet.nms.webclient.map.view.MapViewAction" scope="request">

      <forward name="NoLayoutMap" path="NoLayoutMapView"/>

      </action>

Refer to Struts Configuration file to know more about the design of the Struts Configuration file.

 

To render the map, the viewId of the selected view is passed. If no viewId is specified in the request, ipnet.netmap, the map for the entire network is displayed. Depending on the values returned from the Web NMS Server for the selected map symbol, the map links, parent-child relationships, and map properties, etc. are set. Depending on the permissions set for the user currently logged in, the context menu for each map symbol is populated.

 

Plugging-in Custom Map Symbol Renderer


Rendering map symbols involves painting the map client components such as map symbols, map links and so on in the Map. The shape, color, text over labels etc., for the map client components are decided by a rendering class.

 

The map symbol renderer paints the actual icon at the position determined by the layout. You can write your custom map symbol renderer implementation, by writing your own .js file (which is the action class). And provide the mapping entry in <WebNMS Home>/webclient/map/conf/mapwebclientconfig.xml file. All the default map symbol renderer entries will be present in mapwebclientconfig.xml file within the <renderer-config> tag.

The default symbol renderers and link renderers are provided within the <symbol> tag and <link> tags respectively as given below:

 

 

<renderer-config>

    <symbol name="symbol_normal" className="MapSymbolRenderer"/>

    ..

    <link name="curved" className="MapLinkRenderer"/>

    ..

<renderer-config>

 

 

To add a new symbol renderer, provide an entry in the file within the <renderer-config> in the <symbol> tag.

 

 

<renderer-config>

   <symbol name="symbol_normal" className="MapSymbolRenderer"/>

   <symbol name="symbol_newrenderer" className="MapNewSymbolRenderer"/>    

   ..

    <link name="curved" className="MapLinkRenderer"/>

    ..

<renderer-config>

 

 

Write the corresponding MapNewSymbolRenderer.js file which will be the action class for the renderer implementation. The renderer script must implement the method renderSymbol to render the symbol, and handleUpdate to handle dynamic updates.

 

 

var renderSymbol = function(surface, mapObject){

..

var renderGroupSymbol = function(surface, mapObject){

..

var cacheGroupsAndShapes = function(surface, mapObject,_gfxGroup, _gfxShapes)

..

var handleUpdate = function( props){

..

return{

            renderSymbol: renderSymbol,

            renderGroupSymbol: renderGroupSymbol,

            handleUpdate: handleUpdate

};

//The renderSymbol and handleUpdate are mandatory for handling the rendering of the symbols and dynamic updates in the map.

 

 

 

In the renderSymbol method you can get the surface and symbol property of the object. You should add the logic for painting the symbol component. The x,y value of the map object can be extracted from the symbol props, and shapes created ( line, circle, image , rect )

 

Parameters:

 surface : The reference where you have to render the symbol or link.

 mapObject: The symbol or link properties object.

Steps:

1. Extract x, y property from the mapObject.

2. Create shapes representing the symbol.

3. Create the SVG Group with the created shapes.

4. Store the Group and Shapes objects in memory using MapMemory module using addSymGroup and addSymShape functions.

 

The implementations for the default symbol renderers is present in the <WebNMS Home>\webclient\map\js\SymbolRendererImpl_1.js file. You can refer to this file in the product to create your own MapNewSymbolRenderer.js implementation file.

 

Sample map filter and maps.conf entry for displaying the renderers

 

//map filter entry

p.put("mapSymbolRenderer", "{\"html\"=\"symbol_label\",\"java\"=\"com.adventnet.nms.mapui.PrinterMapRenderer\"}");

 

//The actual entry in maps.conf file with the quote provided as &quot;.

mapSymbolRenderer="{&quot;html&quot;=&quot;symbol_label&quot;,&quot;java&quot;=&quot;com.adventnet.nms.mapui.MapSymbolRendererImpl_4&quot;}"

 

 

To apply the new symbol renderer to your map, double-click on the map and select the new symbol renderer name "symbol_newrenderer" from the SymbolRenderer combobox in the "Display" tab in the map view.

 

Plugging-in Custom Map Link Renderer

 

The map link renderer paints the actual link between the map symbols. You can write your custom map link renderer implementation, by writing your own .js file (which is the action class). And provide the mapping entry in <WebNMS Home>/webclient/map/conf/mapwebclientconfig.xml file. 

 

The default symbol renderers and link renderers are provided within the <symbol> tag and <link> tags respectively as given below:

 

 

<renderer-config>
    <symbol name="symbol_normal" className="MapSymbolRenderer"/>
    ..
    <link name="curved" className="MapLinkRenderer"/>
    ..
<renderer-config>

 

 

To add a new link renderer, provide an entry in the file within the <renderer-config> in the <link> tag.

 

 

<renderer-config>

   <symbol name="symbol_normal" className="MapSymbolRenderer"/>

   ..

    <link name="curved" className="MapLinkRenderer"/>

   <link name="curved_new" className="MapNewLinkRenderer"/>

    ..

<renderer-config>

 

 

Write the corresponding MapNewLinkRenderer.js file which will be the action class for the new link renderer implementation. The link renderer script must implement method renderLink to render the link, and handleUpdate to handle dynamic updates.

 

var renderLink = function(surface,mapLinkObj){
..
var createCurveLine = function(surface,_gfxGroup, _gfxShapeArray, srcX, srcY, destX, destY, _statusColorCode){
..
var cacheGroupsAndShapes = function(surface, mapLinkObj, gfxGroup, gfxShapeArray){
..
var handleUpdate = function( props){
..
return{
        renderLink:renderLink,
        handleUpdate: handleUpdate
        };

//The renderLink and handleUpdate methods are mandatory for rendering the links and for dynamic updates in maps.

 

 

In renderLink method you will get the surface to render and the mapLink properties as the parameters. You should add the logic for rendering link using shapes (link, polyline).

 

Rendering a link is similar to rendering a symbol, where the shapes and groups are created using the shapes by extracting the source and destination from the properties.

 

The implementations for the default link renderers are present in the <WebNMS Home>\webclient\map\js\MapLinkRenderer.js file. You can refer to this file in the product to create your own MapNewLinkRenderer.js  implementation file.

 

Sample map filter and maps.conf entry for displaying the renderers

 

//map filter entry

p.put("mapLinkRenderer", "{\"html\"=\"no_link\",\"java\"=\"com.adventnet.nms.mapui.MapLinkRendererImpl\"}");

//The actual entry in maps.conf file with the quote provided as &quot;.

mapSymbolRenderer="{&quot;html&quot;=&quot;curved&quot;,&quot;java&quot;=&quot;com.adventnet.nms.mapui.MapSymbolRendererImpl_3&quot;}"

 

 

To apply the new link renderer to your map, double-click on the map and select the new link name "curved_new"  from the LinkRenderer combobox in the "Display" tab.

 

 

Plugging in Custom Map Layout Implementation

 

The layouts determine the positioning of the map symbols on the map. There are 5 default renderers supported by the webclient. The layout entries with the layout name and className mapping will be present in <WebNMS Home>/webclient/map/conf/mapwebclientconfig.xml file within the <layout-config> tag.

 

 

<layout-config>
    <layout name="grid" className="GridLayout"/>
    <layout name="3Dimension" className="GridLayout"/> <!-- No Support for 3D layout in webclient so routing to gridlayout -->
    ..
   ..
    <layout name="switch" className="SwitchLayout"/>
    <layout name="router" className="SwitchLayout"/>
</layout-config>

 

 

To add a new layout, provide an entry in the file within the <layout-config> tag.

 

 

<layout-config>
    ...
    <layout name="router" className="SwitchLayout"/>
    <layout name="newswitch" className="NewSwitchLayout"/>
</layout-config>

 

 

Write the corresponding NewSwitchLayout.js file which will be the action class for the new layout implementation.  The layout script must implement the layout method and handleUpdate method for handling dynamic updates.

 

define(["MapEventHandler","GridCoordinates","MapMemory","MapOperations"],

        function(mapEventHandler, gridCoordinates, mapMemory,mapOperations){

       var layoutMap = function(mapContainerID,surface, symbolsToLayout)                

        ..

        ..

        ..

      var handleUpdate = function( props ){

       ..

       ..

    }

    return{

        layoutMap: layoutMap,

        handleUpdate: handleUpdate

    };    
});

//The renderSymbol and handleUpdate are mandatory for handling the

rendering of the symbols in the map.

 

 

 

In the Layout script layoutMap method, you will get the mapContainerId. This is the ID of the DOM which holds the Surface.

 

Parameters:

surface: The surface object in which symbol is to be rendered.

symbolsToLayout: Array of symbol names to be layouted in the maps. These are fetched from the MapMemory getAllSymbols() functions.

 

Steps:

 

1. Compute the x, y for each symbol and modify the x,y of each symbol. You can use the screen dimension and other symbol related functions from MapMemory if needed.

 

The implementations for the layouts are present in the <WebNMS Home>\webclient\map\js\ folder. You can refer to any of the Layout files. eg. GridLayout.js and GridCoordinate.js file to write your own layout class.

 

The supported layouts for a map should be added to the topology property and current topology property of the map during map creation.

 

Sample map filter and maps.conf entry for displaying the layouts.

 


//map filter entry

p.put("topology","grid,star,ring,flow");
p.put("currentTopology","grid");

 

//maps.conf entry

topology="grid(width=5;height=7;gapX=13;gapY=15;scroll=vertical;isPercentage=true),star,ring,flow"

 

 

To apply the layout to your map from the web client user interface, double-click on the map and select the layout "newswitch"  from the CurrentTopology combobox in the "Display" tab.

  1. Note: The layout in the web client map toolbar options are displayed based on the "topology" entries of the map. The topology property entries are added when creating the map through map filter class or maps.conf .

Refer to Web NMS User Guide to know more about Map operations in the Web client.

 

Event Handling in Symbols and Links:

Symbol event is handled in SymbolEventHandlers.js for every symbol. Symbol events are binded in MapManager Call Symbol Renderer function.You can modify this code and attach more handlers for events in SymbolRenderers based on your requirement.

 

Link event is handled in LinkEventHandlers.js for every link. You can modify this code based on your requirement.

 

 

Map Limitations

    1. Delay of few seconds will be noticed when rendering more than 200 symbols.

    2. Links will not be present in Group views.

    3. Trying to Show/Hide tree panel when zoomed map view will refresh the page.

    4. Menu name update will not take effect dynamically.

    5. Groups cant be deleted. Instead can be ungrouped, saved, and deleted from map.

    6. Map object based (Symbol, Group) anchor property is not valid as of now in web client maps. The map based "Autoplacement" property is effective in map layouts.

    7. Group status is based on max severity of its child symbol's status.

 

Plugging in Google Maps

 

The facility introduced by Google Maps enables embedding the Google Maps as background for the Map Views in the Web Client. The pages constructed using JavaScript can use these APIs to create a Google Map background for the Map views. Map Symbols can be placed in the desired location based on the geographic latitude and altitude. The GMap View can be created from the Interface itself. When there is requirement to create the map and add more map symbols on server startup, the Map APIs can be used.

 

Files Involved in GMaps

 

File Name File Location

Description

GMapDetails.xml

webclient/map/conf/

The default list of locations are stored in this file. New set of locations can be added to this file by providing the latitude and longitude of the location. The Google Map API key that is required for embedding the Google Maps in the client is also stored in this file. The Maps API key is valid for the server domain to which the client is connected

 

 

 

Creating a GMap

 

Getting the reference to MapAPI is the first step in manipulating the map objects. Before operating on the objects, you need to get a reference of MapAPI. The creation of GMaps and placing the GMapSymbols on the map is similar to the creation of maps in the Java client using MapAPI. The map details added for GMap is updated in the GMapSymbol table. There are two main steps in the creation of GMap.

  1. Note: Refer to  "Manipulating Maps and Map Objects" section for more details on creating a map using MapAPI.

 

Adding a Google Map

 

The Google Map must be created by setting the required properties using the mapApi.addMap(java.lang.String mapname, java.util.Properties p) method. The sample code for adding the GMaps is available in the "Manipulating Maps and Map Objects" section of the Developer Guide.

 

Adding a Map Object (GMapSymbol)  

   

The GMapSymbols can be placed over the newly created GMaps using the addObjects(java.lang.String className, java.util.Vector mapObjects) method. It must be ensured that the GMap exists before adding the GMapSymbols. All the necessary properties for object must be specified before updating the GMapSymbol objects in the GMap. The sample code for adding the GMapSymbols is available in the "Manipulating Maps and Map Objects" section of the Developer Guide.

 

Adding More Location

 

The list of locations displayed in the drop down list can be modified by editing the <Web NMS Home> webclient/map/conf/GMapDetails.xml file. The main attributes that determine the location in Google Maps are the latitude and longitude of the place. These properties must be entered in the GMapDetails.xml file along with the location name (area name). The server must be restarted to display the modified list in the GMap addition page.

 

 

   Refer to Web NMS User Guide to know more about GMap operations in the Web client.

 


Copyright © 2013, ZOHO Corp. All Rights Reserved.