This article is the third 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 second part, Working with the Map Extent was published yesterday. The remaining articles in this series will be published this week.

The previous article briefly introduced the concept of events and pointed you to an example that showed you how to get the current extent through the use of Map events, and specifically the “onExtentChange” Map event. Today I would like to expand on the concept of events and how they are implemented within the ArcGIS Server JavaScript API. Events are actions that are typically triggered by end users. This can include actions such as the click of a mouse, dragging the map in a pan operation, loading a page, executing a task, clicking a button, and many other actions.

Event Basics

The ArcGIS Server JavaScript API is an asynchronous, event-driven API that uses a publish/subscribe pattern. The asynchronous nature of the API means that your application can retrieve data from the server asynchronously in the background without interfering with the display and behavior of the existing page. This means that the content of your application does not have to be reloaded with every request. As I mentioned, the API also follows a publish/subscribe pattern which means that your application will need to 'register' events that are important for the functionality of the application with “listeners” which will respond to the triggering of these events. Listeners are simply code blocks that execute in response to an event that has been fired on the application side. For instance, in the example above, the “onExtentChange” Map event is registered to a code block that displays the current map extent. Let’s look at how this is accomplished.

Adding Event Listeners

In the ArcGIS JavaScript API, events are registered to listeners through the dojo.connect method. In the code example above, we’re registering the “onExtentChange” event found on the map object to the showExtent listener. The showExtent listener is simply a JavaScript function that receives an extent object from the caller, and prints out the min and max x and y coordinates.

Removing Event Listeners

You should always remove listeners when your application is being closed to avoid memory leaks. This can be accomplished through the use of the Map.onUnload event in conjunction with dojo.disconnect. The onUnload event is fired when the map is closed, and dojo.disconnect removes the connect between an event and the method being referenced.

Commonly Used Events

The Map object currently has 27 events that can be initiated including onClick, onExtentChange, onLayerAdd, onLoad, onMouseDrag, onMouseWheel, onZoom, onPan and many others. I should point out that it is not necessary to write listener code functions for every single event that can be triggered. You only write event handlers for those events that are necessary for your application. When an event is triggered for which you have not registered and written a handler, the event is simply ignored in the application. Several other objects provide important events including the Layer, GraphicsLayer, and InfoWindow.

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