Interactive Map App Events

An interactive map instance will trigger numerous events, such as when the visible region changes or layers are added or removed. You can respond to any of these changes by adding your own event handler on your map instance.

The following events are currently triggered by a Map instance:

Event Description
ready Fired when the map is initialized once its center and zoom have been set for the first time.
layer:select Fired when a layer element is toggled on from the Layers Panel.
layer:change Fired when a layer element is changed from the Layers Panel, specifically for layer elements configured with multiple segments not as filters.
layer:change:option Fired when a layer element’s filters are changed from the Layers Panel, specifically for layer elements configured with multiple segments as filters.
layer:deselect Fired when a layer element is toggled off from the Layers Panel.

Adding Event Listeners

You add event listeners to your map instance using the on() method. This method requires the event name, as a string, and the handler function to call when the event is triggered.

For example, you may want to perform a certain action when a user changes the selected filters associated with an active layer, such as updating the data using your custom VectorSource. Just add an event listener for the layer:change:option event:

map.on('layer:change:option', (e) => {
    console.log('changed layer option', e.data);
    const source = e.data.source;
    if (source && source.service) {
        source.service.filter(e.data.value);
        source.reload();
    }
});

Your event handler function will receive a single argument, which is the Event instance that was triggered by the event. In several cases, this Event object will also contain a data property that is an object with additional data or object references associated with the event.

So in the above event handler for a layer:change:option event, we are outputting the value of e.data to the console as that is the data that was associated with the event. For this particular event, this object will contain a value property, which is the current filter value, and a source property, which is the map content source associated with the parent layer, if defined.

Removing Event Listeners

Similar to adding events, you can remove event listeners from a map instance using the off() method. This method only requires the event name, as a string and a reference to the original handler function used in on() to be provided.

Suppose we know we will want to remove the event listener at some point in the future. We’d want to store a reference to the event handler so we can remove it later:

// create a reference to the event handler function
const handleLayerFilterClick = (e) => {
    console.log('changed layer option', e.data);
    const source = e.data.source;
    if (source && source.service) {
        source.service.filter(e.data.value);
        source.reload();
    }
}
map.on('layer:change:option', handleLayerFilterClick);

// later we decide to remove the listener
map.off('layer:change:option', handleLayerFilterClick);

If you know you won’t need to reference the event handler function later, then you can just provide the handler function as an inline paramter to on() instead.

Last modified: May 09, 2019