Setting and using extents in a mapE-mail This Topic Printable Version Give Us Feedback

One common operation when using a map is setting the map's extent or getting the extent for use in other operations.

Default extent

If you include no extent information when you initialize a map, the default extent is the initial extent, which is the extent of the map as it was last saved in the map document. If you are using more than one service, the default extent is the initial extent of the base map or first layer added.

Setting a new starting extent

If you want the starting extent to be something other than the default extent, you have several options for setting this new extent.

Setting the beginning extent when using multiple services

When you include multiple services in the same application, the default extent is the initial extent of the base layer. If you want the beginning extent to be something new, and you know the extent ahead of time, you can include that extent in the Map constructor.

In some cases, you may not know the extent ahead of time. In other cases, you know you want to use the extent of a secondary layer. For example, the ArcGIS Online services all have a world extent. Instead of the world extent, you may want your map extent to be the extent of your local data.

In the following example, two services or layers are used. The base layer is an ArcGIS Online layer with a world extent. The second layer has an extent of the State of Kansas, which is the desired extent to use. The initLayers() function creates the two layers. You must create a second function to set the extent since you cannot call properties or events on a class before the class has been loaded. In this case, the function createMapAddLayers() is called after the layer onLoad has been fired for both map services. This function creates the map, sets the extent to myService2, and then adds both map services to the map. The initial map extent uses the Layer.fullExtent property as defined by the map service. If you want to use the initial extent instead, you would use Layer.initialExtent. 

function initLayers() {
  var primaryMapServiceURL = "http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer";
  var myService1 = new esri.layers.ArcGISTiledMapServiceLayer(primaryMapServiceURL);

  var secondaryMapServiceURL = "http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Petroleum/KGS_OilGasFields_Kansas/MapServer";
  myService2 = new esri.layers.ArcGISDynamicMapServiceLayer(secondaryMapServiceURL, {opacity:0.75});

  var layerLoadCount = 0;
  //When both layers have loaded, run addLayersSetExtent
  dojo.connect(myService1, "onLoad", function(service) {
    layerLoadCount += 1;
    if (layerLoadCount === 2) {
  	createMapAddLayers(myService1,myService2);
    }
  });

  dojo.connect(myService2, "onLoad", function(service) {
    layerLoadCount += 1;
    if (layerLoadCount === 2) {
      createMapAddLayers(myService1,myService2);
    }
  });
}

//Create a map, set the extent, and add the services to the map.
function createMapAddLayers(myService1,myService2) {
  //create map
  myMap = new esri.Map("mapDiv", { extent:myService2.fullExtent });
  myMap.addLayer(myService1);
  myMap.addLayer(myService2);
}

Getting the current extent using Map events

You can get the current extent of the map by using the Map.onExtentChange event.

In the following example, Map.onExtentChange is referenced in the init() function. When a user pans or zooms the map, a callback is made to the showExtent() function. The onExtentChange event has built in objects. The first object is the extent. In this example, the object is named ext, and the object properties include xmin, ymin, xmax, and ymax. In the showExtent() function, the four extent values are concatenated together in a string for display on the HTML page. 

   function init(){
     var myMap = new esri.Map("mapDiv");

     var mapServiceURL = "http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer";
     myMap.addLayer(new esri.layers.ArcGISTiledMapServiceLayer(mapServiceURL));
     myMap.addLayer(mapServiceURL);

     dojo.connect(myMap, "onExtentChange", showExtent);
   }

   function showExtent(ext){
     var s = "";
     s = "XMin: " + ext.xmin +
       " YMin: " + ext.ymin +
       " XMax: " + ext.xmax +
       " YMax: " + ext.ymax;
     dojo.byId("onExtentChangeInfo").innerHTML = s;
   }

Getting the current extent using Map.extent

You can get the current extent of the map by using the Map.extent property. This property is a read-only property. If you want to set the extent, you need to use the Map.setExtent method.