Event Handling in ArcGIS for JavaScript

ArcGIS for JavaScript is a mature and powerful framework for creating interactive maps and layers. Your map can respond to users easily by leveraging the robust collection of ArcGIS events. Just about every widget or module comes with a set of events that are easy to hook up.

Since the ArcGIS for JavaScript API is asynchronous, an event-driven approach is encouraged. Operations do not finish immediately or in sequence, so you must listen for information to determine when an object is ready. The event model is flexible and intuitive—events are very simple to register and you may keep track of multiple handlers for the same event. 

Registering Events

ArcGIS for JavaScript works hand-in-hand with Dojo (most prominently you may notice the dependency injection technique). For event registration, it works nicely with dojo/on, a general-purpose event handler module based on the event model practiced by modern browsers. Add dojo/on to your list of injected modules, then register events using this format:

moduleName.on("eventName", callbackFunc);

The Load Event

One important event to capture is the loading of the map itself. Many functionalities are dependent upon the map being ready, so it is common practice to put initialization functions in the callback for this event.

var map = new Map("map", {
     basemap: "streets",
     center: [-79, 38]
});

map.on("load", function () {
     initDrawing();
     initEditing();
});

Many other ArcGIS modules furnish a load event. It is best used to enable dependent functionality or prepare user inputs for interaction (such as setting visibility or adding a tabindex to widgets on the map).

var basemapGallery = new BasemapGallery({           
     showArcGISBasemaps: true,
     map: map
}, "basemapGallery");
     
basemapGallery.startup();
     
basemapGallery.on("load", function () {
     $(".baseMapGall .dijitTitlePaneTitle").attr("tabindex", 10);
     $(".baseMapGall").removeClass("hidden");
});

Start and End Events

ArcGIS frequently offers different flavors of the same basic event for more fine-grained control. For actions like zooming, editing, and dragging, start and end events are provided. Start events are useful for when you wish to restrict the behavior a user is about to do, and end events are well suited for triggering actions based on what the user just finished doing.

var editToolBar = new Edit(map);

//After a graphic has been edited, update it in your backing data store
editToolBar.on("vertex-move-stop", function (e) {
     updateItem(e.graphic.attributes.id, e.graphic.geometry);
});

editToolBar.on("graphic-move-stop", function (e) {
     updateItem(e.graphic.attributes.id, e.graphic.geometry);
});

editToolBar.on("vertex-delete", function (e) {
     updateItem(e.graphic.attributes.id, e.graphic.geometry);
});

editToolBar.on("scale-stop", function (e) {
     updateItem(e.graphic.attributes.id, e.graphic.geometry);
});

editToolBar.on("rotate-stop", function (e) {
     updateItem(e.graphic.attributes.id, e.graphic.geometry);
});

Info Window Events

The info window is a perfect base for custom content that changes depending on the characteristics of the graphic it represents. Modify the info window on selection-change. This event fires just before the info window appears, or before the content changes to a new graphic after clicking a caret button (< or >) to navigate a stack of graphics. Since the trigger occurs before the window view is bound to the graphic, it is the proper time to alter or change the visibility of its content.

Say there is a permissions model that determines which graphics a user can edit. Add a custom edit button to the info window, then control its visibility and visual cues with the following event:

map.infoWindow.on("selection-change", function () {
     //Get the newly selected graphic      
     var graphic = map.infoWindow.getSelectedFeature();

     if (graphic != null) {
          //Initially hide the edit button
          $(".esriPopup .btn-edit").addClass("hidden");
          //Set the title pane to a dark dray color as another visual cue
          $(".esriPopup .titlePane").css({"background-color": "#444"});
          if (canEditGraphic(graphic.attributes.id)) {
               //Show the edit button and color the title pane something nice
               $(".esriPopup .btn-edit").removeClass("hidden");
               $(".esriPopup .titlePane").css({"background-color": “darkcyan”});
          }
     }
});

Unregistering Events

It is best practice to remove event handlers when the application closes to avoid memory leaks. This is accomplished using the map unload event. For an application with more than a couple events, keep track of your handlers by putting them in a collection.

var events = [];   

events.push(map.on("load", function () {…}));

events.push(map.on("unload", function () {
     for (var i = 0; i < events.length; i++) {
          events[i].remove();
     }
}));

Demo

Check out this plunk to view a demo of these concepts: