Map Methods

This section describes members used to manipulate a widget.

addMarker(markerOptions, callback)

Adds a marker to the map.

Parameters:
markerOptions: Object|Array
An object defining added marker options. These options include 'location'(required), 'tooltip'(optional), 'click'(optional) and 'text'(optional).
callback: function
A callback function called after the marker has been added.
Return Value: jQuery.Promise
A Deferred jQuery object.

The markerOptions object can include the following fields.

  • location (required) - the marker location. You can specify the location in one of the following formats:
    • { lat: 40.749825, lng: -73.987963};
    • "40.749825, -73.987963";
    • [40.749825, -73.987963];
    • 'Brooklyn Bridge,New York,NY';
  • tooltip (optional) - the marker tooltip;
  • clickAction (optional) - an action performed when the marker is clicked;
  • text (optional) - the marker caption.
  • iconSrc (optional) - a URL pointing to the custom icon to be used for the marker.
Show Example:
jQuery
<div id="myMap" data-bind="dxMap: { width:'100%', height: '85%' }"></div>
<div data-bind="dxButton: { text: 'Add marker', clickAction: function () { markerOptionsVisible(true); } }"></div>
<div data-bind="dxPopup: { visible: markerOptionsVisible, title: 'Add marker' }">
  <div class="dx-fieldset">
    <div class="dx-field">
      <div class="dx-field-label">Title</div>
      <div class="dx-field-value" data-bind="dxTextBox: { value: markerTitle }"></div>
    </div>
    <div class="dx-field">
      <div class="dx-field-label">Tooltip</div>
      <div class="dx-field-value" data-bind="dxTextBox: { value: markerTooltip }"></div>
    </div>
    <div class="dx-field">
      <div class="dx-field-label">Location</div>
      <div class="dx-field-value" data-bind="dxTextBox: { value: markerLocation }"></div>
    </div>
  </div>
  <div data-bind="dxButton: {text: 'Add', clickAction: add }"></div>
  <div data-bind="dxButton: { text: 'Cancel', clickAction: function () { markerOptionsVisible(false); } }"></div>
</div>
suggestedMarkers = [
  { title: "DevExpress", tooltip: "<p>The <b>DevExpress</b> office</p>", location: "505 N. Brand Blvd, 16th Floor Glendale CA 91203 USA" },
  { title: "New York", tooltip: "<p>Somewhere in <b>New York</b></p>", location: "40.749802, -73.981018" },
  { title: "London", tooltip: "<p>Center of <b>London</b></p>", location: "London, United Kingdom" },
  { title: "Opera House", tooltip: "<p>Sydney Opera House</p>", location: "Sydney Opera House" },
];
var newMarkerDataIndex = 0;
markerOptionsVisible = ko.observable(false);
markerTitle = ko.observable(suggestedMarkers[newMarkerDataIndex].title);
markerTooltip = ko.observable(suggestedMarkers[newMarkerDataIndex].tooltip);
markerLocation = ko.observable(suggestedMarkers[newMarkerDataIndex].location);

//A function that adds a route
add = function () {
  $("#myMap").dxMap("instance").addMarker({
    title: markerTitle(),
    tooltip: markerTooltip(),
    location: markerLocation()
  }, function () { DevExpress.ui.notify("Marker added", "info", 1000); });
  newMarkerDataIndex = (newMarkerDataIndex >= suggestedMarkers.length - 1 ? 0 : newMarkerDataIndex + 1);
  markerTitle(suggestedMarkers[newMarkerDataIndex].title);
  markerTooltip(suggestedMarkers[newMarkerDataIndex].tooltip);
  markerLocation(suggestedMarkers[newMarkerDataIndex].location);
  markerOptionsVisible(false);
};
body{
  text-align: center;
}
.dx-button{
  margin:10px;
}

addRoute(routeOptions, callback)

Adds a route to the map.

Parameters:
options: Object|Array
An object containing the route locations.
callback: function
A callback function called after the route has been added.
Return Value: jQuery.Promise
A Deferred jQuery object.

The options object should include the locations field, containing an array of route locations. Each location can be specified in any of the following formats.

  • { lat: 40.749825, lng: -73.987963}
  • "40.749825, -73.987963"
  • [40.749825, -73.987963]
  • 'Brooklyn Bridge,New York,NY'
Show Example:
jQuery
<div id="myMap" data-bind="dxMap: { width: '100%', height: '85%' }"></div>
<div data-bind="dxButton: { text: 'Add route', clickAction: function () { routeOptionsVisible(true); } }"></div>
<div data-bind="dxPopup: { visible: routeOptionsVisible, title: 'Add route' }">
  <div class="dx-fieldset">
    <div class="dx-field">
      <div class="dx-field-label">Color</div>
      <div class="dx-field-value" data-bind="
        dxLookup: { dataSource: colors, value: routeColor },
        attr: { style: 'color:' + routeColor() + ';' }
      ">
        <div data-options="dxTemplate: {name: 'item'}">
          <div data-bind="text: $data"></div>
        </div>
      </div>
    </div>
    <div class="dx-field">
      <div class="dx-field-label">Width: <span data-bind="text: routeWidth"></span></div>
      <div class="dx-field-value" data-bind="dxSlider: { value: routeWidth, min: 1, max: 15 }"></div>
    </div>    
    <div class="dx-field">
      <div class="dx-field-label">Start</div>
      <div class="dx-field-value" data-bind="dxLookup: {
        dataSource: citiesDataSource,
        displayExpr: 'capital',
        valueExpr: 'capital',
        value: startCity
      }">
        <div data-options="dxTemplate: { name: 'item' }">
          <b data-bind="attr: { style: 'color:' + $data + ';' }, text: $data"></b>
        </div>
      </div>
    </div>
    <div class="dx-field">
      <div class="dx-field-label">End</div>
      <div class="dx-field-value" data-bind="dxLookup: {
        dataSource: citiesDataSource,
        displayExpr: 'capital',
        valueExpr: 'capital',
        value: endCity
      }">
        <div data-options="dxTemplate: {name: 'item'}">
          <b data-bind="text: capital"></b>
        </div>
      </div>
    </div>
  </div>
  <div data-bind="dxButton: { text: 'Add', clickAction: add }"></div>
  <div data-bind="dxButton: { text: 'Cancel', clickAction: function () { routeOptionsVisible(false); } }"></div>
</div>
colors = ["red", "green", "blue", "brown", "magenta", "darkcyan", "darkorange", "peru"];
routeOptionsVisible = ko.observable(false);
routeColor = ko.observable(colors[0]);
routeWidth = ko.observable(2);
startCity = ko.observable();
endCity = ko.observable();

//An object passed to the dataSource option
//of the dxLookup widget containing route locations
citiesDataSource = {
  load: function (loadOptions) {
    var dfd = new $.Deferred();
    $.get("/Content/data/states.txt", function (data) {
      if (loadOptions.searchString === undefined)
        dfd.resolve(data);
      else
        dfd.resolve($.grep(data, function (e) {
          return e.name.toLowerCase().indexOf(loadOptions.searchString.toLowerCase()) !== -1;
        }));
    }, "json");
    return dfd.promise();
  },
  lookup: function (key) {
    if (!key)
      return null;
    var dfd = new $.Deferred();
    $.get("/Content/data/states.txt", function (data) {
      for (var i = 0; i < data.length; i++){
        if (data[i].capital === key) {
          dfd.resolve(data[i]);
          return;
        }
      }
    }, "json");
    return dfd.promise();
  }
};

//A function that adds a route
add = function () {
  $("#myMap").dxMap("instance").addRoute({
    color: routeColor(),
    width: routeWidth(),
    locations: [startCity() + " USA", endCity() + " USA"]
  }, function () { DevExpress.ui.notify("Route added", "info", 1000); });
  routeOptionsVisible(false);
};
body{
  text-align: center;
}
.dx-button{
  margin:10px;
}

beginUpdate()

Prevents the component from refreshing until the endUpdate method is called.

The beginUpdate and endUpdate methods allow you to apply several modifications to the component. After the beginUpdate method is called, the component does not raise events, and does not update the UI until the endUpdate method is called. Using these methods prevents excessive component updates when changing multiple component settings at once.

endUpdate()

Enables the component to refresh after the beginUpdate method call.

The beginUpdate and endUpdate methods allow you to apply several modifications to the component. After the beginUpdate method is called, the component does not raise events, and does not update the UI until the endUpdate method is called. Using these methods prevents excessive component updates when changing multiple component settings at once.

instance()

Returns an instance of this component class.

Return Value: Object
An instance of this component class

Use this method to access other methods of the component.

option()

Returns the configuration options of this component.

Return Value: Object
An object representing the configuration options of this component.

option(optionName)

Gets the value of the specified configuration option of this component.

Parameters:
optionName: String
The name of the option to get.
Return Value: any
The value of the specified option.

If you need to get the value of a configuration option field, specify the path to the required field.

option(optionName, optionValue)

Sets a value to the specified configuration option of this component.

Parameters:
optionName: String
The name of the required option.
optionValue: any
The value you wish to assign to the required option.

To set a value to the configuration option field, specify the path to the required field.

option(options)

Sets one or more options of this component.

Parameters:
options: Object
An object containing the required configuration options.

removeMarker(marker)

Removes a marker from the map.

Parameters:
A marker options object or marker index specifying the marker to be removed.

Show Example:
jQuery
<div id="myMap" data-bind="dxMap: { markers: mapMarkers, width: '100%', height: '85%' }">
</div>
<div data-bind="dxButton: { text: 'Remove marker', clickAction: function () { removeOptionsVisible(true); } }">
</div>
<div data-bind="dxPopup: { visible: removeOptionsVisible, title: 'Remove marker' }">
  <div class="dx-fieldset">
    <div class="dx-field">
      <div class="dx-field-label">Marker</div>
      <div class="dx-field-value" data-bind="dxLookup: {
        dataSource: markersDataSource,
        value: selectedMarkerId,
        displayExpr: 'title',
        valueExpr: 'id',
        searchEnabled: false
      }"></div>
    </div>
  </div>
  <div data-bind="dxButton: { text: 'Remove', clickAction: remove }">
  </div>
  <div data-bind="dxButton: { text: 'Cancel', clickAction: function () { removeOptionsVisible(false); } }">
  </div>
</div>
removeOptionsVisible = ko.observable(false);
selectedMarkerId = ko.observable();

mapMarkers = [
  { title: "DevExpress", tooltip: "<p>The <b>DevExpress</b> office</p>", location: "505 N. Brand Blvd, 16th Floor Glendale CA 91203 USA" },
  { title: "New York", tooltip: "<p>Somewhere in <b>New York</b></p>", location: "40.749802, -73.981018" },
  { title: "London", tooltip: "<p>Center of <b>London</b></p>", location: "London, United Kingdom" },
  { title: "Opera House", tooltip: "<p>Sydney Opera House</p>", location: "Sydney Opera House" },
];

var forceRefresh = false;
//An object passed to the dataSource option 
//of the dxLookup widget containing existing markers
markersDataSource = DevExpress.data.createDataSource({
  load: function (loadOptions) {
    if (loadOptions.refresh || forceRefresh) {
      if (forceRefresh)
        forceRefresh = false;
      var markers = $("#myMap").dxMap("instance").option("markers");
      for (var i = 0; i < markers.length; i++)
        markers[i].id = i;
      return markers;
    }
  },
  lookup: function (key) {
    return key ? $("#myMap").dxMap("instance").option("markers")[key] : null;
  }
});

//A function that removes the selected marker
remove = function () {
  $("#myMap").dxMap("instance").removeMarker(selectedMarkerId());
  forceRefresh = true;
  markersDataSource.load();
  removeOptionsVisible(false);
};
body{
  text-align: center;
}
.dx-button{
  margin:10px;
}

removeRoute(route)

Removes a route from the map.

Parameters:
A route options object or a route index specifying the route to remove.

Show Example:
jQuery
<div id="myMap" data-bind="dxMap: { routes: mapRoutes, width: '100%', height: '85%' }">
</div>
<div data-bind="dxButton: { text: 'Remove route', clickAction: function () { removeOptionsVisible(true); } }">
</div>
<div data-bind="dxPopup: { visible: removeOptionsVisible, title: 'Remove route' }">
  <div class="dx-fieldset">
    <div class="dx-field">
      <div class="dx-field-label">Route</div>
      <div class="dx-field-value" data-bind="dxLookup: {
        dataSource: routesDataSource,
        value: selectedRouteId,
        displayExpr: 'name',
        valueExpr: 'id',
        searchEnabled: false
      }"></div>
    </div>
  </div>
  <div data-bind="dxButton: { text: 'Remove', clickAction: remove }">
  </div>
  <div data-bind="dxButton: { text: 'Cancel', clickAction: function () { removeOptionsVisible(false); } }">
  </div>
</div>
removeOptionsVisible = ko.observable(false);
selectedRouteId = ko.observable();

mapRoutes = [
  { color: "red", name: "Olympia - Topeka Wichita", locations: ["Olympia USA", "Topeka Wichita USA"]},
  { color: "magenta", name: "Phoneix - Raleigh", locations: ["Phoneix USA", "Raleigh USA"] },
  { color: "blue", name: "Santa-fe - ST. Paul", locations: ["Santa-fe USA", "ST. Paul USA"] },
  { color: "green", name: "Leansing - Denver", locations: ["Leansing USA", "Denver USA"] },
  { color: "darkorange", name: "Sacramento - Austin", locations: ["Sacramento USA", "Austin USA"] }
];

var forceRefresh = false;
//An object passed to the dataSource option 
//of the dxLookup widget containing existing routes
routesDataSource = DevExpress.data.createDataSource({
  load: function (loadOptions) {
    if (loadOptions.refresh || forceRefresh) {
      if (forceRefresh)
        forceRefresh = false;
      var routes = $("#myMap").dxMap("instance").option("routes");
      for (var i = 0; i < routes.length; i++)
        routes[i].id = i;
      return routes;
    }
  },
  lookup: function (key) {
    return key ? $("#myMap").dxMap("instance").option("routes")[key] : null;
  }
});

//A function that removes the selected route
remove = function () {
  $("#myMap").dxMap("instance").removeRoute(selectedRouteId());
  forceRefresh = true;
  routesDataSource.load();
  removeOptionsVisible(false);
};
body{
  text-align: center;
}
.dx-button{
  margin:10px;
}