Skip to main content
Version: 4.0

Migration Guide

On November 22, 2021 we released Mappedin JS v4. This short migration guide explains the steps needed to migrate from version 1.

Initialization​

  • Removed mappedin.initialize in favor of getVenue and showVenue. This makes it easier to create applications where the map is not displayed immediately but the venue data is used such as directories of locations. getVenue downloads the map data from the server.
  • Added showVenue method, which renders the map in the given HTMLElement and resolves when the map is interactive. That is when you can add interactive polygons or draw labels on the map.
showVenue<T extends Mappedin>(
  el: HTMLElement,
  venue: T,
  options?: TMapViewOptions): Promise<MapView>

In v4, the map is initialized by getting the data and then displaying it. It also simplifies the options for rendering the map.

async function init() {
	const venueData = await getVenue({
		clientId: '<clientId>',
		clientSecret: '<clientSecret>',
		venue: '<venue>',
	});

	const mapView = await showVenue(document.getElementById('mappedin-map'), venueData);
}
document.addEventListener('DOMContentLoaded', init);

In v1, the map would be initialized like this:

const options = {
	mapview: {
		antialias: 'AUTO',
		mode: Mappedin.modes.TEST,
	},
	venue: {
		venue: '<venue>',
		clientId: '<clientId>',
		clientSecret: '<clientSecret>',
		perspective: 'Website',
		things: {
			venue: ['slug', 'name'],
			maps: ['name', 'elevation', 'shortName'],
		},
	},
};

Mappedin.initialize(options, document.getElementById('mappedin-map'));

The two types of labels​

Floating Label, previously called Smart Labels are the default type of label. These labels feature a marker at a given location, followed by text describing that location. Legacy labels were renamed to a more descriptive name Flat Label. Their text is drawn on top of the location polygon.

Both accept an their own appearance objects to customize their appearance. Floating label marker default size has been reduced slightly.

Using Floating Labels and customizing their appearance:

mapView.labelAllLocations({
	appearance: {
		marker: {
			size: 12,
			backgroundColor: {
				active: '#bf4320',
				inactive: '#efefef',
			},
		},
	},
});

Using Flat Labels and customizing their appearance:

mapView.labelAllLocations({
	flatLabels: true,
	appearance: {
		color: '#0055bb',
	},
});

Improved events​

Removed old Events (onPolygonClicked, etc) in favor of new ENUM-based events with payload type checking:

  • E_SDK_EVENT.STATE_CHANGE
  • E_SDK_EVENT.POLYGON_CLICKED
  • E_SDK_EVENT.NOTHING_CLICKED
  • E_SDK_EVENT.MAP_CHANGED

You can import the events with import { E_SDK_EVENT } from "@mappedin/mappedin-js";.

To listen to polygon clicks, you can start listening to that event in the init function after showVenue has resolved and the polygons have been made interactive:

mapView.addInteractivePolygonsForAllLocations();
mapView.on(E_SDK_EVENT.POLYGON_CLICKED, (polygon) => {
	console.log(`Polygon with id ${polygon.id} clicked!`);
});

Upgraded API for getting directions​

  • Removed Navigator in favor of new Journey API
MapView.Journey {
    draw: (directions: MappedinDirections, options?: TJourneyOptions) => void;
    setStep: (step: number) => void;
    clear: () => void;
}

Simplified BlueDot API​

API Documentation for the new simplified BlueDot API is at https://docs.mappedin.com/web-sdk-api/v4/v4.1.5/classes/BlueDotLayer.html.

MapView.BlueDot.enable({ showBearing: true });
MapView.BlueDot.disable();

To listen to BlueDot position updates you can now do the following:

mapView.BlueDot.on(E_BLUEDOT_EVENT.POSITION_UPDATE, (payload) => console.log(payload));

Available BlueDot events:

  • BLUEDOT_POSITION_UPDATE
  • BLUEDOT_STATE_CHANGE

Simplified Camera API​

New simplified Camera API (Documentation) moved from mapView.CameraControls

MapView.Camera {
    zoom,
    tilt,
    rotation,
    focusOn(),
    set(),
    animate()
}

We can react to to camera events (E_CAMERA_EVENT) by setting the listener:

mapView.Camera.on(E_CAMERA_EVENT.ROTATION_CHANGED, (payload) => {
	console.log(payload, 'radians');
});

Available camera events are:

  • USER_INTERACTION_START
  • USER_INTERACTION_END
  • ZOOM_CHANGED
  • ROTATION_CHANGED
  • TILT_CHANGED

Setting camera rotation, tilt or zoom (or a combination of these) is easy with the new set method:

mapView.Camera.set({
	rotation: Math.PI, // radians
});

Tooltip changes​

Aligned tooltip API to be closer to Markers so that it takes a position indicated by a node or a coordinate followed by an options object.

createTooltip(
node: MappedinNode | MappedinCoordinate,
options:
  | TCreateTextTooltipOptions
  | TCreateCustomInnerHTMLTooltipOptions
  | TCreateCustomTooltipOptions

Using geocoordinates​

mapView.getPositionLatLon and mapView.convertTo3DMapPosition are deprecated. Use MappedinMap.createCoordinate() instead to create a marker based on latitude and longitude.

const coordinate = venue.maps[1].createCoordinate(43.52091191291561, -80.53964096309828);

mapView.createMarker(coordinate, `<div style="background: white; padding: 4px">Hello world</div>`, {
	anchor: MARKER_ANCHOR.CENTER,
});

Path display​

When calculating path widths, we previously used scaled units. In v4 these are set in meters. The default nearRadius value in PathOptions has been changed from 20 to 1.8. Correspondingly the farRadius is now 2.3 * nearRadius by default. These values are approximately the same, however some variation may occur depending on the venue scale. oldNearRadiusInMetres = 20 * map.scale will give you the exact value to use with v4 to keep the path width identical. Documentation at https://docs-staging.mappedin.net/web-sdk-api/v4/v4.1.5/modules.html#TPathOptions

The default for drawing a path was changed so that the path pulse fires only once and the animation takes longer. To keep the previous infinite pulse behavior you can set the following path options when drawing a Journey:

mapView.Journey.draw(directions, {
	pathOptions: {
		pulseIterations: Infinity,
	},
});

Other deprecations​

  • mapView.colors deprecated. Use mapView.setHoverColor for hover, and pass color directly elsewhere
  • Removed Outdoor Context
  • Removed VIEW_STATE