TomTom LogoDocs
Products
Resources
Pricing
Sign in
Maps SDK for JavaScript
Introduction
Guides
Examples
API Reference

Module lifecycle events

VERSION 1.0.0-rc.3PUBLIC PREVIEW

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

CallModules
applyConfig, updateConfig, resetConfigAll
setKnob, resetKnobEvery module with a knob catalogue
setVisibleEvery module with visible, and BaseMapModule with { layerGroups }
setIconsVisibleTrafficIncidentsModule
setHillshadeVisible, setElevationVisibleTerrainModule
setPalette, setColorStops, setHeight, setFiltersTrafficAreaAnalyticsModule
get(map, config) on a module the map already hasStyle-owned modules
setStyle(style, { resetState: true }), which resets every moduleAll

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);
    }
});
ModuleTriggered byPayload
PlacesModuleshow / showConnections{ places } / { connections }
RoutingModuleshowRoutes / showWaypoints{ routes } / { waypoints }
GeometriesModule, ReachableRangesModuleshowthe PolygonFeatures given
CustomGeoJSONModuleshow(data, sourceName){ sourceName, data }, once per source when show names none
TrafficIncidentDetailsModuleshowthe TrafficIncidentDetails given
TrafficAreaAnalyticsModuleshowthe TrafficAreaAnalytics given
  • 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');