JavaScript/jQuery VectorMap - End-User Interaction

This section contains guides on the following user interaction features:

• Panning
• Zooming
• Hovering
• Click handling
• Element selection

When a map in the VectorMap UI component goes beyond the size of the container, panning can be used to view the regions that do not fit the container. To pan a map, the user drags the mouse pointer or one finger (when using a touchscreen device) along or across the map. Panning can also be performed using the arrows of a pan control, which is a part of the control bar. Clicking the button located in the center of the pan control resets panning settings.

Technically, panning is changing the view area. VectorMap provides a number of properties and methods for operating with the view area. Their capabilities are described in the following subtopics.

By default, any map is centered on a (0, 0) geographical point. To center the map on a different point, specify the center property that accepts an array of two values representing the longitude and the latitude of a point.

var vectorMapCfg = {
    // ...
    center: [-87.627778, 41.881944] // centers the map on Chicago
};

If you need to restrict the view area to specific coordinates, set the bounds property. This property accepts an array of geographical coordinates in the following format: [minLongitude, maxLatitude, maxLongitude, minLatitude].

var vectorMapCfg = {
    // ...
    bounds: [-135, 60, -65, 20] // displays the USA by default
};

When you need to place the center into a different geographical point, use the center(centerCoordinates) method. Call this method with an array of two values: the longitude and the latitude of the new center, similar to the array the center property accepts.

vectorMapInstance.center([-106.61, 35.110833]); // moves the center to Albuquerque

Calling the same method without arguments returns the current coordinates of the center.

Similarly, you can change the current view area using the viewport(viewportCoordinates) method. It accepts an array of geographical coordinates in the following format: [minLongitude, maxLatitude, maxLongitude, minLatitude].

vectorMapInstance.viewport([15, 10, 110, 75]); // navigates the map to Eurasia

To get the current coordinates of the view area, call the same method without arguments. Note that changing the view area with the viewport(viewportCoordinates) methods may raise the center change and zoom change events if the center coordinates and zoom factor have been changed when you set new coordinates for the view area.

When panning is performed, the center change event is raised. You can handle this event using a callback function assigned to the onCenterChanged property. When implementing this function, use the object passed to it as the parameter. Fields of this object are described in the onCenterChanged property description. Among these fields, you can find the updated center coordinates.

var vectorMapCfg = {
    // ...
    onCenterChanged: function (info) {
        // specify required actions here
    }
};

Zooming allows the end-user to enlarge a map in order to view those parts of it that are difficult to distinguish. To zoom in and zoom out of a map, the user can scroll the mouse wheel or use the spread and pinch gestures (when using a touchscreen device). Zooming can also be performed using a zoom bar, which is a part of the control bar.

When zoomed, a map does not exceed the container size. Instead, it leaves only a certain region of itself visible. In order to navigate to concealed regions of the map, panning must be used.

Apart from zooming in UI, VectorMap supplies you with several properties and methods configuring and managing zooming in code. For more information about these properties, navigate to the following subtopics.

In code, zoom is measured by a zoom factor. The zoom factor represents the relation between the width (or height) after and the width (or height) before zooming. Simply put, the zoom factor shows how much a map is zoomed relatively to its original size. For example, the zoom factor equaling 2 means that the map is twice larger than the original.

For setting initial zoom, assign a number greater than 1 to the zoomFactor property.

var vectorMapCfg = {
    // ...
    zoomFactor: 2.5 // zooms the map 2.5 times
};

To perform zooming in code, use the zoomFactor(zoomFactor) method. When calling this method, pass the required value of the zoom factor as the argument as it is illustrated by the code snippet below.

vectorMapInstance.zoomFactor(1.5); // zooms the map 1.5 times

Calling the same method without arguments returns the current value of the zoom factor.

You can perform specific actions when the zoom factor has been changed. Implement a callback function performing these actions and assign it to the onZoomFactorChanged property. When implementing the function, use the object passed to it as the parameter. Fields of this object are described in the onZoomFactorChanged property description. Among these fields, you can find the updated zoom factor.

var vectorMapCfg = {
    // ...
    onZoomFactorChanged: function (info) {
        // specify required actions here
    }
};

In the VectorMap UI component, when a user hovers the mouse pointer over a map element (an area or a marker), this element changes its appearance. This state of the element is called "hovered state".

Of all map elements, only areas and markers can be in the hovered state. To learn how to configure their hover-related features, see the Area Hover and Marker Hover topics.

Additionally, an area or a marker in the hovered state can be accompanied by a tooltip, which displays descriptive information about the area or marker. For more information on how to configure tooltips, refer to the tooltip object description.

Hover-related area settings reside in the layer configuration object. By default, areas already respond to hovering over them, so there is no need to specify any properties. But if this feature is not required, assign false to the hoverEnabled field of the area layer.

var vectorMapCfg = {
    // ...
    layers: [{
        type: 'area',
        // ...
        hoverEnabled: false
    }]
};

If you did not switch the hovering off, specify the appearance of areas in the hovered state using the hoveredColor and hoveredBorderColor properties. Both of them specify the color, only the former specifies it for areas, while the latter specifies it for area borders.

var vectorMapCfg = {
    // ...
    layers: [{
        type: 'area',
        // ...
        hoveredColor: 'blue', // paints areas blue in the hovered state
        hoveredBorderColor: 'red' // paints area borders red in the hovered state
    }]
};

Note that specified directly in the area layer, the hoveredColor and hoveredBorderColor properties are applied to all map areas at once. If you need to set these properties for a specific area, specify them within the object returned by the customize function. When implementing this function, use the Layer Element object to identify the area. This object is accessible using the function's argument as well as using the this object.

var vectorMapCfg = {
    // ...
    layers: [{
        type: 'area',
        // ...
        hoveredColor: 'blue', // paints areas blue in the hovered state
        customize: function (elements) {
            $.each(elements, function (i, element) {
                if (element.attribute('name') == 'Kansas'
                    element.applySettings({ hoveredColor: 'green' }); // paints 'Kansas' green in the hovered state
            });
        }
    }]
};

Hover-related marker settings reside in its layer configuration object. Map markers have all the same hovering properties that map areas have: hoverEnabled switches the hovering on/off, hoveredColor and hoveredBorderColor specify the color of markers and their borders.

var vectorMapCfg = {
    // ...
    layers: [{
        type: 'marker',
        // ...
        hoverEnabled: true, // enables hovering (as hovering is enabled by default, may not be set)
        hoveredColor: 'blue', // paints markers blue in the hovered state
        hoveredBorderColor: 'red' // paints marker borders red in the hovered state
    }]
};

Being set directly in the marker layer, the color-specifying properties are applied to all map markers at once. To set these properties for a specific marker, specify them within the object returned by the customize function. When implementing this function, use the Layer Element object to identify the marker. This object is accessible using the function's argument as well as using the this object.

var vectorMapCfg = {
    // ...
    layers: [{
        type: 'marker',
        // ...
        hoveredColor: 'blue', // paints markers blue in the hovered state
        customize: function (elements) {
            $.each(elements, function (i, element) {
                if (element.attribute('text') == 'Memphis') {
                    element.applySettings({ hoveredColor: 'green' }); // paints 'Memphis' green in the hovered state
                }
            });
        }
    }]
};

VectorMap allows you to handle clicks on the map. The onClick function is called each time an end-user clicks the map.

The following subtopics explain how to implement a callback function for three click cases.

To handle a click on a map area, implement a callback function and assign it to the onClick property. Inside the function, check whether a layer element was clicked and whether the layer type of the element is 'area'. When implementing this callback function, use the object passed to it as the parameter. Fields of this object are described in the onClick property description. Fields and methods of this object are documented in the Layer Element class description.

var vectorMapCfg = {
    // ...
    onClick: function (e) {
        var clickedElement = e.target;
        if (clickedElement != null && clickedElement.layer.type == "area") {
            // specify required actions here
        }
    }
};

Frequently, it is required that you select an area on a click. Learn how to implement this from the Implement Selection topic.

Handling a click on a marker and handling a click on an area are similar in nature. You need to implement a callback function and assign it to the onClick property. Inside the function, check whether a layer element was clicked and whether the layer type of the element is 'marker'. When implementing this callback function, use the object passed to it as the parameter. Fields of this object are described in the onClick property description. Fields and methods of this object are documented in the Layer Element class description.

var vectorMapCfg = {
    // ...
    onClick: function (e) {
        var clickedElement = e.target;
        if (clickedElement != null && clickedElement.layer.type == "marker") {
            // specify required actions here
        }
    }
};

Frequently, it is required that you select a marker on a click. Learn how to implement this from the Implement Selection topic.

When you need to handle any click on a map regardless of whether it was on an area or a marker, implement a callback function for the onClick property of the root configuration object. When implementing this function, use the object passed to it as the parameter. Fields of this object are described in the onClick property description. Among these fields, you can find an object that represents the jQuery event extended by the x and y fields. They contain the coordinates of the clicked point.

var vectorMapCfg = {
    // ...
    onClick: function (info) {
        // specify required actions here
    }
};

The X and Y coordinates are calculated relatively to the client area, i.e., the UI component container. To convert them into map coordinates, use the convertCoordinates(x,y) method.

To make your map more interactive, supply your map with the selection feature. In the VectorMap UI component, an end-user may be able to select areas and markers. While selected, the appearance of an area or a marker differs from unselected ones. This appearance can be configured separately.

Selection is configured identically for areas and markers. Therefore, in the following subtopics, when both areas and markers are in question, they are referred to as "map elements" for brevity.

In a common scenario, a map element must become selected when a user clicks it. Selection in this scenario is implemented using the onClick callback function. For more information on handling the click event for map elements, refer to the Area Click and Marker Click topics. The following code shows how to enable a user to select/deselect map elements by a click.

var vectorMapCfg = {
    // ...
    onClick: function (info) {
        var clickedElement = info.target;
        if (clickedElement != null)
            clickedElement.selected(!clickedElement.selected());
    }
};

In this code snippet, the selected method of a map element is first called without arguments to obtain the current selection state. Then, the same method is called once more, this time with the reverted value of the selection state passed as the argument.

Selection can be conducted in single or multiple mode. In single mode, which is enabled by default, only one map area or marker can be in the selected state at a time. In multiple mode, several map areas or markers can be in the selected state at the same time. To specify the required mode, use the selectionMode property of a layer.

var vectorMapCfg = {
    // ...
    layers: [{
        // ...
        selectionMode: 'single' // 'multiple' | 'none'
    }]
};

In addition, you can use the selectionMode property to disable the selection capability. For this purpose, assign 'none' to this property.

The appearance of map elements in the selected state can be customized using the selectedColor and selectedBorderColor properties. Both of them specify the color, only the former specifies it of map elements, while the latter specifies it of their borders.

var vectorMapCfg = {
    // ...
    layers: [{
        // ...
        selectedColor: 'blue', // paints the layer blue in the selected state
        selectedBorderColor: 'red' // paints the layer borders red in the selected state
    }]
};

Note that specified directly in the layer configuration object, the selectedColor and selectedBorderColor properties are applied to all map elements at once. If you need to set these properties for a specific area or marker, specify them within the object returned by the customize function. When implementing this function, use an elements array to get all layer elements. This object is passed to the customize function as the argument.

var vectorMapCfg = {
    // ...
    layers: [{
        type: 'area',
        // ...
        selectedColor: 'blue', // paints areas blue in the selected state
        customize: function (elements) {
            $.each(elements, function (i, element) {
                if (element.attribute('name') == 'California') {
                    element.applySettings({ selectedColor: 'green' }); // paints 'California' green in the selected state
                }
            });
        }
    }, {
        type: 'marker',
        // ...
        selectedColor: 'blue', // paints markers blue in the selected state
        customize: function (elements) {
            $.each(elements, function (i, element) {
                if (element.attribute('text') == 'Memphis')
                    element.applySettings({ selectedColor: 'blue' });  // paints the 'Memphis' area in blue
            });
        }
    }],
};

Map elements may appear selected when the map is loaded. To accomplish this, implement the customize function that must return an object with the isSelected field set to true for those areas or markers that must appear selected. The following code snippet provides an example of implementing this function.

var vectorMapCfg = {
    // ...
    layers: [{
        type: 'area',
        // ...
        selectedColor: 'blue', // paints areas blue in the selected state
        customize: function (elements) {
            $.each(elements, function (i, element) {
                if (element.attribute('name') == 'Ohio') {
                    element.applySettings({ isSelected: true }); // makes 'Ohio' appear selected
                }
            });
        }
    }, {
        type: 'marker',
        // ...
        selectedColor: 'blue', // paints markers blue in the selected state
        customize: function (elements) {
            $.each(elements, function (i, element) {
                if (element.attribute('text') == 'Detroit')
                    element.applySettings({ isSelected: true }); // makes 'Detroit' appear selected
            });
        }
    }],
};

To select a map element in code, use its selected(state) method. Calling the same method without arguments returns the current selection state of the map element.

To call the selected method, you need to obtain the Layer Element object. If you are calling this method from a click-handling function, it is not an issue, because these objects are passed there as the argument. But in case you need to call it outside this function, call the getLayers(), getLayerByName() or getLayerByIndex() method.

var areas = mapInstance.getLayerByName('myAreaLayer'); // gets the area layer
areas[0].selected(true); // selects the area with index 0
var markers = mapInstance.getLayerByName('myMarkerLayer'); // gets the markers layer
markers[0].selected(true); // selects the marker with index 0

You can also clear selection settings for all map elements simultaneously using the clearSelection() method.

mapInstance.clearSelection(); // deselects all areas and markers

When an layer element is selected/deselected, the function assigned to the onSelectionChanged property is invoked. This function accepts an object as the parameter. Among fields of this object, you can find the selected/deselected element .

var vectorMapCfg = {
    // ...
    onSelectionChanged: function (info) {
        // specify required actions here
    }
};

To identify whether a map element has been selected or deselected, use its selected() method inside the selection-handling function.