dxMap

The dxMap widget displays the map at the specified location using a specified zoom level. It also supports markers and routes.

View Demo

Map Providers

The widget supports Bing and Google map providers to display the map. Use the provider option to specify the required map provider. You can assign one of the following values to the provider option.

  • "bing"
    Uses the bing maps API.

  • "google"
    Uses the Google maps API.

  • "googleStatic"
    Uses the Google static maps API.

JavaScript
var mapOptions = {
    provider: "bing"
}

The supported map providers require the API key used to identify your application. You can specify the key using the key option, which takes an object containing any of the bing, google and googleStatic properties. Each of these properties holds the API key for the corresponding map provider.

JavaScript
var mapOptions = {
    key:{
        bing: BING_API_KEY,
        google: GOOGLE_API_KEY,
        googleStatic: GOOGLE_STATIC_API_KEY
    }
}

For more information on API keys, refer to the required map provider documentation.

Map Types

Each map provider supports similar map types, but type names are different. The dxMap widget includes the type option that specifies the map type. The option accepts the "hybrid", "roadmap" and "satellite" values, which are based on names of the Google map types. If you use the Bing map provider, the widget automatically maps option values in the following way.

  • "hybrid" -> "Aerial"
  • "roadmap" -> "Road"
JavaScript
var mapOptions = {
    provider: "bing",
    type: "roadmap"
}

Adjust Location And Zoom Level

You can specify the location displayed at the center of the widget using the center option. The widget accepts the same location formats as the current map provider. Thus you can use the following location formats.

  • { lat: 40.749825, lng: -73.987963 }
  • "40.749825, -73.987963"
  • [40.749825, -73.987963]
  • 'Brooklyn Bridge,New York,NY'
JavaScript
var mapOptions = {
    center: {
        lat: 40.749825,
        lng: -73.987963
    }
}

The displayed area size is defined by the map zoom level, which is specified using the zoom option. The stronger the zoom level, the smaller area that is displayed.

JavaScript
var mapOptions = {
    zoom: 10
}

By default, the widget sets the automatically calculated zoom value each time a marker or a route is added to the map. In this case, zoom is set to the maximum value, allowing all markers and routes to be displayed at the same time. Set the autoAdjust option to false to disable this behavior.

JavaScript
var mapOptions = {
    center: "40.749825, -73.987963",
    zoom: 10,
    autoAdjust: false
}

Working With Markers

The dxMap widget can display markers on the map. The array of displayed markers is held in the markers option. Each item of the array is an object that can have the following properties.

  • location (required)
    An object, a string, or an array specifying the marker location. Supports the same location formats as the center option.
  • tooltip (optional)
    Takes on an object containing the text and isShown fields. The text field specifies the tooltip text. The isShown field takes on a Boolean value that specifies whether a tooltip is visible by default or not. If the tooltip should be hidden by default, pass the tooltip text directly to the tooltip property.
  • onClick (optional)
    A callback function performed when the marker is clicked.
  • iconSrc (optional)
    A URL pointing to the custom icon to be used for the marker.

Add And Remove Markers

To add and remove markers, use the addMarker(markerOptions) and removeMarker(marker) methods respectively.

JavaScript
var addMarker = function(){
    var map = $("#mapContainer").dxMap("instance");
    map.addMarker({
        location: "40.749825, -73.987963"
    });
}
var removeMarker = function(){
    var map = $("#mapContainer").dxMap("instance");
    map.removeMarker(0);
};

The addMarker(markerOptions) method argument should contain the added marker configuration object. The argument passed to the removeMarker(marker) method can contain a marker options object, marker index, or an array of marker option objects to be removed.

You can pass the array of the required markers to the markers option to display them immediately after the widget is created.

JavaScript
var mapOptions = {
    markers: [
        { location: "40.749825, -73.090443" },
        { location: "42.743244, -71.594375" },
        { location: "37.058435, -74.903842" }
    ]
}

In MVVM approach, provide two-way binding between the markers option and the corresponding field of a view or application model to manage markers. The widget automatically updates the markers list when you add to or remove items from the array.

Angular Approach
JavaScript
var myApp = angular.module('myApp', ['dx']);
myApp.controller("defaultCtrl", function ($scope) {
    $scope.mapMarkers = [];
    $scope.addMarker = function(){
        $scope.mapMarkers.push({ location: "40.749825, -73.987963" });
    }
    $scope.removeMarker = function(){
        $scope.mapMarkers.pop();
    };
});
HTML
<div ng-controller="Controller">
    <div dx-map="{
    bindingOptions: {
        'markers': 'mapMarkers'
    }"></div>
</div>
Knockout Approach
JavaScript
var mapMarkers = ko.observableArray();
var mapOptions = {
    markers: mapMarkers
}
var addMarker = function(){
    mapMarkers.push({ location: "40.749825, -73.987963" });
}
var removeMarker = function(){
    mapMarkers.remove({ location: "40.749825, -73.987963" });
};
HTML
<div data-bind="dxMap: { markers: mapMarkers }"></div>

Working With Routes

The dxMap widget can display routes on the map. The array of displayed routes is held in the routes option. Each item of the array is an object that can have the following properties.

  • locations (required)
    Contains an array of locations making up the route.
  • mode (optional)
    Specifies a transportation mode to use in the displayed route. Acceptable values: 'driving' (set by default) and 'walking'.
  • color (optional)
    Specifies the color of the line displaying the route.
  • weight (optional)
    Specifies the thickness of the line displaying the route in pixels.
  • opacity (optional)
    Specifies the opacity of the line displaying the route.

Add And Remove Routes

To add and remove routes, use the addRoute(routeOptions) and removeRoute(route) methods respectively.

JavaScript
var addRoute = function(){
    var map = $("#mapContainer").dxMap("instance");
    map.addRoute({
        color: 'red',
        weight: 2,
        locations: [
            [40.748302, -73.978518],
            [40.748625, -73.992363],
            [40.757823, -73.995297]
        ]
    });
}
var removeRoute = function(){
    var map = $("#mapContainer").dxMap("instance");
    map.removeRoute({
        color: 'red',
        weight: 2,
        locations: [
            [40.748302, -73.978518],
            [40.748625, -73.992363],
            [40.757823, -73.995297]
        ]
    });
};

The addRoute(routeOptions) method argument should contain the added route configuration object. The argument passed to the removeRoute(Route) method can contain a route options object, route index, or an array of route option objects to be removed.

You can pass the array of the required routes to the routes option to display them immediately after the widget is created.

JavaScript
var mapOptions = {
    routes: [
        {
            color: 'red',
            weight: 2,
            locations: [
                [40.748302, -73.978518],
                [40.748625, -73.992363],
                [40.757823, -73.995297]
            ]
        },
        {
            color: 'blue',
            weight: 2,
            locations: [
                [40.747802, -73.995297],
                [40.746302, -73.978518],
                [40.757823, -73.978518]
            ]
        },
        {
            color: 'green',
            weight: 2,
            locations: [
                [40.749802, -73.981018],
                [40.749825, -73.987963],
                [40.755823, -73.986397]
            ]
        }
    ]
}

In MVVM approach, provide two-way binding between the routes option and the corresponding field of a view or application model to manage markers. The widget automatically updates the markers list when you add to or remove items from the array.

Angular Approach
JavaScript
function Controller($scope) {
    $scope.mapRoutes = [];
    $scope.addRoute = function(){
        $scope.mapRoutes.push({
            color: 'red',
            weight: 2,
            locations: [
                [40.748302, -73.978518],
                [40.748625, -73.992363],
                [40.757823, -73.995297]
            ]
        });
    }
    $scope.removeRoute = function(){
        $scope.mapRoutes.remove({
            color: 'red',
            weight: 2,
            locations: [
                [40.748302, -73.978518],
                [40.748625, -73.992363],
                [40.757823, -73.995297]
            ]
        });
    };
};
HTML
<div ng-controller="Controller">
    <div dx-map="{
    bindingOptions: {
        routes: 'mapRoutes'
    }"></div>
</div>
Knockout Approach
JavaScript
var mapRoutes = ko.observableArray();
var mapOptions = {
    routes: mapRoutes
}
var addRoute = function() {
    mapRoutes.push({
        color: 'red',
        weight: 2,
        locations: [
            [40.748302, -73.978518],
            [40.748625, -73.992363],
            [40.757823, -73.995297]
        ]
    });
}
var removeRoute = function() {
    mapRoutes.remove({
        color: 'red',
        weight: 2,
        locations: [
            [40.748302, -73.978518],
            [40.748625, -73.992363],
            [40.757823, -73.995297]
        ]
    });
};
HTML
<div data-bind="dxMap: { routes: mapRoutes }"></div>