Module lifecycle events

Module lifecycle events fire when a module changes, whatever caused it. For user interactions with the map, use user interaction events.

• config-change - The module's configuration changed. Every module has it.
• shown-features - The module drew data you passed to one of its show methods.

Both are on the module's own events, next to its user events, and never on a named scope. A module has one configuration and one stream of shown data.

In the demo below, the search results list draws itself from shown-features, so it matches the pins whether a picked place, a page of results or Load more drew them.

config-change

The handler receives the module's whole configuration after the change, as getConfig() returns it. After resetConfig(), it can be undefined. Use it to keep your UI in sync, whichever code made the change:

import { TerrainModule } from '@tomtom-org/maps-sdk/map';

const terrain = await TerrainModule.get(map);
const toggle = document.querySelector('#hillshade-toggle');

terrain.events.on('config-change', (config) => {
    toggle.checked = config?.hillshade?.visible ?? false;
});

toggle.addEventListener('change', () => terrain.setHillshadeVisible(toggle.checked));

What triggers config-change

The configuration you create a module with fires nothing. To save what the handler receives and replay it later, see Saving and replaying a configuration.

shown-features

The handler receives the data a show method drew. A module with several show methods reports them all on one stream, and the payload tells you which one ran:

import { PlacesModule } from '@tomtom-org/maps-sdk/map';

const places = await PlacesModule.create(map);

places.events.on('shown-features', (features) => {
    if ('places' in features) {
        updateResultsPanel(features.places);
    } else {
        updateConnectionsPanel(features.connections);
    }
});

• It fires once the data is on the map, before the show promise resolves, so getShown() already returns it.
• Modules with no show don't accept a shown-features handler, so neither events.on('shown-features', …) nor events.off('shown-features') compiles on them. These are BaseMapModule, POIsModule, TrafficFlowModule, TrafficIncidentsModule, TerrainModule and StylingFoundationsModule.

Cleanup

events.on returns a function that removes only that handler. events.off(type) removes every handler of a type, user events included:

const unsubscribe = places.events.on('config-change', saveSettings);
unsubscribe(); // other config-change handlers keep firing

places.events.off('shown-features');
places.events.off('click');

Related guides and examples

Related guides

• Events - Which event to use for what
• User interaction events - Clicks, hovers and event states
• Map modules - Changing, saving and replaying a configuration
• Map styles - Reacting to a style switch with addStyleChangeHandler

Related examples

• Search playground - A results list drawn from shown-features