Map modules

A map module adds one capability to a TomTomMap: showing places or routes, filtering traffic, shading terrain, restyling the whole map. Every module shares one contract, which this page owns:

• Two kinds, by who owns the layers: style-owned or data-owned, which decides the factory and how many instances a map takes.
• One configuration surface: the configuration given at creation, then applyConfig(config), updateConfig(partial) and resetConfig(), read back with getConfig() and reported by events.on('config-change', …). See Changing a setting.
• Settings as data: each module publishes a knob catalogue, and setKnob sets any setting by its id.
• Restored on style changes: data, configuration and layer placement come back after every setStyle.
• Typed user events per module, handed your original data: user interaction events.
• Tree-shaken: a module you do not import is not in your bundle.

Types of modules

Who owns the sources and layers a module controls decides both the factory you call and how many instances make sense on one map.

Style-owned modules — get(map, config?)

• They control sources and layers the map style already provides — the base map, POIs, the traffic tiles, the terrain elevation — under fixed, global ids, and display no data of their own.
• One per map: get() is a lookup, so a second call returns the same instance. Two components can each ask for the terrain without sharing a reference.
• get(map) without a configuration leaves the module's configuration as it is; with one, it applies it to the existing instance.
• The traffic and terrain modules' get() adds their style part when the style lacks it.
• To handle events on part of what one covers, scope its events rather than looking for a second module.

Data-owned modules — create(map, config?)

• They add the GeoJSON sources, layers and sprite images they need, and own them for their whole lifetime, every id suffixed per instance.
• Many per map: create() builds a new, independent module every time — one set of places per search, one route per plan.

Per-module reference

Who owns what

Everything visible on the map has exactly one owner, and the owner follows from who owns the layers. Every module has knobs of its own: each style-owned module decides whether and how its part of the loaded style shows, the Styling Foundations module the foundations that reach across every part — sizes, the map colours, projection and sky — and each data-owned instance everything about the layers it adds itself. The dashed line is the only place a knob reaches past its module: the data-owned modules read the accent as their default colour.

In detail:

Two consequences:

• The rows do not cross. Knobs on the loaded style never write a data-owned module's layers, and a data-owned module never restyles the base map under it: recolouring a route is RoutingModule configuration, recolouring the roads it runs on is colors.roadMajor. The accent and the borrowed looks are read, not written.
• The foundations and a part's own look meet on the same layers, and compose: one engine per map applies every style knob, whichever module holds it, so labels.sizeFactor and the POIs' sizeFactor multiply on the POI labels, and all of them land on top after a style switch.

Within a style-owned module, the finer settings only narrow what its coarser ones show. A road part or the POI micro markers never show while their layer group or the POIs are hidden, and showing those again keeps a part's false; the POIs' zoomShift rewrites the same layer filters filters.categories narrows, in either order.

Each module guide opens with a What this module owns line that applies this rule to that module.

Changing a setting

Every setting changes through three calls each module has: applyConfig(config) replaces the whole configuration, updateConfig(partial) changes the top-level properties it is given, and setKnob sets one setting by its catalogue id.

• updateConfig merges one level deep. A nested object it is given replaces the one there, so to change one nested field, spread the current part or set its knob:

  import { placesKnobCatalogue, setKnob } from '@tomtom-org/maps-sdk/map';
  
  placesModule.updateConfig({ label: { ...placesModule.getConfig()?.label, color: '#c2185b' } });
  setKnob(placesModule, placesKnobCatalogue, 'label.color', '#c2185b');
  

• Named setters are for visibility: setVisible / isVisible and the parts that hide on their own (see Visibility under Appearance vocabulary). The only others are TrafficAreaAnalyticsModule's per-metric setPalette, setColorStops, setHeight and setFilters. A named setter is always set<Setting>.

Saving and replaying a configuration

getConfig() is the export and applyConfig() the import: a module's configuration that went through JSON, given back to applyConfig, holds the same configuration and draws the same layers. Keep one to restore a user's map, attach it to a support report, or replay it in a test.

localStorage.setItem('places', JSON.stringify(placesModule.getConfig()));

// Later, on the same module or a new one
placesModule.applyConfig(JSON.parse(localStorage.getItem('places')));

Most modules' configurations are JSON whole, styling's knobs included. Five modules also take functions or image elements, which JSON cannot carry. Each has a type for the part that survives, which its reference page details; a replay adds the rest back in code:

JSON.stringify drops a function without a trace, but turns an image element into {}, which does not replay. Give icon images as URLs, data URIs or SVG text, and a place or waypoint title as a MapLibre expression, to keep the whole configuration serializable. POIsModule's icon.categoryIcons takes image elements too, with no type to leave them out.

const state = JSON.parse(saved); // PlacesModuleSerializableConfig
placesModule.applyConfig({
    ...state,
    connections: { ...state.connections, label: { ...state.connections?.label, title: (connection) => connection.name } },
});

The configuration is what a module draws with, not the data it shows: replay show() with the data too.

Appearance vocabulary

A concept has one name on every module that has it. The table lists the shared appearance terms, the rule each follows, and the exact properties that carry it; a module missing from a row does not have that concept.

Every setting as data

A module's display settings are also published as a knob catalogue: static data, readable with no map loaded, that a control panel builds its controls from and an agent checks a value against. An entry's id is the setting's path in the module's configuration, where a number indexes a list (filters.any.0), and its kind says which value it takes and which fields come with it. The entry type is KnobEntry, and the kinds are KnobKind:

• range is the span a control offers, with the step a slider uses. Its bounds say which ends a value must keep to:

  bounds	A value must be	For example
  hard	between min and max	an opacity, a *Factor
  hard-min	at least min; above max it still applies	a height in metres
  soft	any number	an offset

• default is present where one value holds everywhere. Without it, the description says what decides: the style, the accent, the global configuration.

• A setting that takes a MapLibre expression, a callback or a structured object stays in the configuration. The plain-value alternatives of a setting that also takes an expression are in its entry, and they are what the module's …KnobValueOf<ID> type names.

• The styling catalogue and the map effects plugin's use the same kinds.

Setting a knob by its id

Three functions work a knob by its catalogue id, on every module, the Styling Foundations module and the map effects plugin's MapEffects included:

• setKnob(module, catalogue, id, value) sets one setting and keeps every other one; a value its entry refuses changes nothing.

• getKnob(module, catalogue, id) reads the value in force: the one set, else what the module knows it to be (a look knob of a style-owned module reads the loaded style), else the entry's default.

• resetKnob(module, catalogue, id) unsets one, and drops the objects it leaves empty, so a knob set and then reset leaves the configuration as it was. resetConfig() unsets them all.

• knobEntryOf(catalogue, id) reads one entry: kind, range or options, default and description.

• validateKnobValue(entry, value) is the check alone, for a value from a form or a language model.

• validateKnobValue and setKnob throw a RangeError naming the knob and what it expects; the four that take an id throw an Error for one the catalogue lacks.

• A literal id types the value it takes; an id held as any string, as in a panel looping over a catalogue, takes any value and is checked when set.

The path is the same for every module, and a knob only ever redraws what its own module draws:

import { getKnob, knobEntryOf, resetKnob, setKnob, trafficFlowKnobCatalogue, validateKnobValue } from '@tomtom-org/maps-sdk/map';

setKnob(trafficFlow, trafficFlowKnobCatalogue, 'filters.roadCategories.values', ['motorway', 'trunk']);
getKnob(trafficFlow, trafficFlowKnobCatalogue, 'visible'); // false until set: the entry's default
resetKnob(trafficFlow, trafficFlowKnobCatalogue, 'filters.roadCategories.values');

const knob = knobEntryOf(trafficFlowKnobCatalogue, 'filters.roadCategories.values'); // kind, range or options, default
validateKnobValue(knob, ['motorway', 'cart track']); // RangeError: … 'cart track' is not

The traffic config playground sets every flow and incidents knob this way, from controls built off the two catalogues.