This article is the second in a five part series covering the ArcGIS JavaScript API and the ArcGIS JavaScript Extension for the Google Maps API. It was previously published at GeoChalkboard in the form of a six-part article, and has been reproduced here with permission. The first part, Getting Started was published yesterday. The remaining articles in this series will be published this week.

Continuing with our series on the ArcGIS Server JavaScript API, today we will cover various ways that you can work with the map extent. If you don’t include extent information when an instance of the map is created in your code, the default or initial extent will be the extent of the map as it was last saved in the map document (.mxd). For example, the code snippet below does not include any extent information in the constructor for the map. This would result in a default extent being applied which was the extent of the map when it was last saved in the map document.

Here is the result.

In the event that you are using more than one service, the default extent will be the initial extent of the base map or first layer added.

Setting the Initial Extent

There are several options for setting the initial map extent through your code. The easiest way to do so is through the constructor for the map. The constructor for the Map object takes a required parameter which points to div element on your page, and an options parameter which can contain the initial extent of the map as well as other options such as the layer used to initialize the map, the inclusion of navigation controls, and others. Click here to see a full description of the available options that can be included in the constructor.

For instance, the following code snippet shows how you can accomplish setting the extent through the constructor. To set the initial extent of the map you will need to know the min and max x and y values of the extent.

You can also accomplish the same task but in a slightly different manner through the use of the setExtent method on Map as you see in the code example below.

You could also set each property of the extent separately.

Here is the result.

Setting the Initial Extent when using Multiple Services

If you’re using multiple map services in your application, the default extent will be the initial extent of the base layer. If you know the extent you’d like to use ahead of time then you can include the extent in the map constructor as we have shown above. However, at times you will either not know the extent ahead of time or you may want to use the extent of a secondary layer. For instance, if you’re using a map service that shows the extent of the world as your base layer, and a second map service with your local data you’d probably want to set the extent of your application to that of your local data. The code example below from ESRI shows how this can be accomplished through the fullExtent property found on ArcGISMapServiceLayer.

Getting the Current Extent

You can obtain the current map extent through the read-only Map.extent property or through the use of events. The later method for returning the current map extent is through the use of Map events, and specifically the “onExtentChange” event. The topic of events requires a fair amount of explanation so I will save this for my next post, but for now here is an example which uses the “onExtentChange” event to return the current map extent which is then displayed in a div tag below the map.

This article was written by Eric Pimpler at GeoSpatial Training Services. Geospatial Training Services provide a range of geoweb courses.