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
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 throughadd_action. To access the specific clicked feature, attach a native event listener to themapobject 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