For the complete documentation index, see llms.txt. This page is also available as Markdown.

Migrating from V1

How to update V1 hook code to work with the V2 event system.

The developer hook system has changed significantly in V2. If you have custom code built on V1 hooks, it will need to be updated. The changes are straightforward once you understand the pattern, but they touch every hook call you've written.

You can always revert. If you need more time to update your custom code, you can roll back to V1 of the plugin while you work through the migration. V1 and V2 are separate plugin versions.

What Changed

1. The global object is now mwm_v2

V1 used a global mwm object. V2 uses window.mwm_v2.

2. You must wrap subscriptions in onload()

In V1, mwm.add_action() could be called anywhere on the page. In V2, add_action must be called inside an mwm_v2.onload() callback, which ensures your listeners are registered before any events fire:

// V1
mwm.add_action('map_set', (map) => { ... });

// V2
window.mwm_v2.onload(() => {
  window.mwm_v2.add_action('map:loaded', ({ map }) => { ... });
});

3. Event names use colons instead of underscores

V1 Hook
V2 Event

map_set

map:loaded

data_fetched

data:fetched

map_markers_set

features:rendered

map_features_set

features:rendered

map_datalayers_set

features:rendered

loading_icon_done

features:rendered

set_clustering

features:rendered

set_mapstyle

style:loaded

set_terrain

terrain:set

set_interactivity

interaction:set

map_resize_set

map:resize

layer_feature_clicked

layer:click

layer_feature_hovered

layer:mousemove

popup_opened_from_layer_click

popup:open

popup_opened_from_layer_hover

popup:open

popup_closed_from_layer_hover

popup:close

marker_feature_clicked

marker:click

marker_feature_hovered

marker:mouseenter

popup_opened_from_marker_click

popup:open

popup_opened_from_marker_hover

popup:open

popup_closed_from_marker_hover

marker:mouseout

Some V1 hooks (access_token_set, map_library_set, map_size_set, set_customscripts) have no direct equivalent in V2. In most cases map:loaded or features:rendered is the right replacement.

4. Callback arguments have changed

In V1, each hook passed its own specific variable — map_set gave you map, data_fetched gave you postResponse, map_markers_set gave you markers, and so on.

In V2, every event handler receives the same object:

This means you can no longer rely on hook-specific arguments. Update your callbacks to destructure from this object instead:

Note on interaction events: V1 passed the clicked or hovered feature directly to interaction hooks (e.g. clickedFeature, hoveredFeature). V2 does not pass event-specific data through add_action. To access the specific clicked feature, attach a native event listener to the map object using the underlying library's API (e.g. map.on('click', ...)). See Examples for a pattern.

5. Map targeting works differently

In V1, you could target a specific map by appending its ID to the hook name:

In V2 there is no suffix syntax. Instead, check config.id inside the handler:

Custom Scripts

The Custom Scripts feature (entering a global function name in the map's settings) is unchanged. Your existing custom script functions will work in V2 without modification.

Full Before/After Example

Notice that in V2 you no longer need a separate data_fetched hook to cache features — they're available in every handler via features. You also no longer need to wait for map.on('load', ...) inside map:loaded, since subscribing to features:rendered already guarantees the map and features are fully ready.

Last updated