Migrate from v4 to v5

The version 5 of Panoramax Web Viewer has a major rework of its map layers management, as well as its dependencies management. This requires you to change a few things compared to version 4.

Note

If at some point you're lost or need help, you can contact us through issues or by email.

🗺️ MapStyleComposer

The new MapStyleComposer helper allows a more comprehensive management of map layers. Its new features includes:

Ability to switch between more basemaps
Switch between many Panoramax endpoints in the same map, preserving filters & themes during the switch
Inject custom data layers on top of Panoramax layers (dataOverlays), or between basemaps and Panoramax layers (dataUnderlays)
More independent loading of layers, Panoramax endpoint can be loaded before/after basemaps for example

This class replaces a lot of existing code from Map, MapMore, API classes. So, you have a few changes to implement.

🪛 Web component parameters

`metacatalog`

On Viewer, pictures and sequences from our metacatalog (explore.panoramax.fr) are shown by default. This behaviour can be changed by setting metacatalog to:

metacatalog="false" to only display your API data (previous behaviour)
metacatalog="https://another-metacatalog.org" to use another server than public metacatalog

`users` ➡️ `endpoint-to-use` / `user`

The users parameter has been removed from all core components. Instead, for Viewer, you can select by default which Panoramax endpoint should be used. It's either your local API, metacatalog, or a single user from or another server. This is done using endpoint-to-use parameter:

endpoint-to-use="default" for your local API
endpoint-to-use="metacatalog" for metacatalog (if not set to metacatalog="false")
endpoint-to-use="890b6268-7716-4e34-ada9-69985e6c1657" for any specific user UUID (from your local API)
endpoint-to-use="metacatalog_890b6268-7716-4e34-ada9-69985e6c1657" for any specific user UUID from metacatalog

For CoverageMap, users parameter is replaced by user, and only can take a single user UUID at a time.

👂 Events

Various events have been changed in favor of MapStyleComposer ones:

v4 class	v4 event type	v5 class	v5 event type
Map	`background-changed`	MapStyleComposer	`basemap-changed`
Map	`users-changed`	MapStyleComposer	`panoramax-changed`
MapMore	`filters-changed`	MapStyleComposer	`filters-changed`

Also note that new events are available on MapStyleComposer for finer management:

basemap-added
basemap-changed
dataunderlay-added
dataunderlay-changed
panoramax-added
panoramax-changed
theme-changed
filters-changed
dataoverlay-added
dataoverlay-changed

⚙️ Functions

Several functions have been moved as well to MapStyleComposer:

v4 class	v4 function	v5 class	v5 function	v5 property
Map	`hasTwoBackgrounds`	MapStyleComposer	`hasManyBasemaps`
Map	`getBackground`	MapStyleComposer		`basemap`
Map	`setBackground`	MapStyleComposer	`switchBasemap`
Map	`getVisibleUsers`	MapStyleComposer		`panoramax`
Map	`onceLayerReady`	MapStyleComposer	`waitFor`
Map	`setVisibleUsers`	MapStyleComposer	`switchPanoramaxEndpoint`
Map	`filterUserLayersContent`	MapStyleComposer	`setPanoramaxFilters`
Map	`reloadLayersStyles`	MapStyleComposer	`updateMapStyle`
Map	`setVisibleUsers`	MapStyleComposer	`switchPanoramaxEndpoint`
API	`getMapStyle`	MapStyleComposer	`getMapStyle`
API	`getUserMapStyle`	MapStyleComposer	`getMapStyle`

⏯️ Viewer

In order to make a smoother management of loading data from both local API and metacatalog, Viewer now has two API managers in its properties: api (classic) and apiMC (metacatalog). In most of the cases, you may want to replace explicit calls to local API to call to function getAPI in order to get the right API based on map settings.

v5v4

// Get the currently selected API
let api = viewer.getAPI();

// For explicit use of local API
let apiLocal = viewer.api;

// For explicit use of metacatalog API
let apiMC = viewer.apiMC;

// Only local API was available
let apiLocal = viewer.api;

📦 Dependencies

New version got rid of Webpack bundling system, opting for native ES Modules approach. We use Import Maps to load libraries in web browser, instead of having it all in one bundled JS. This approach is more compatible with Photo Sphere Viewer (and Three.js) dependency management, and allows loading plugins.

Note

You can serve the dependencies files both from a CDN, or from local node_modules folder.

v5 (import map)v5 (bundle)v4

In <body>, before classic viewer load, add import map:

<script type="importmap">
{
  "imports": {
    "@fortawesome/fontawesome-svg-core": "https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-svg-core@6.7.2/index.mjs",
    "@fortawesome/free-regular-svg-icons": "https://cdn.jsdelivr.net/npm/@fortawesome/free-regular-svg-icons@6.7.2/index.mjs",
    "@fortawesome/free-solid-svg-icons": "https://cdn.jsdelivr.net/npm/@fortawesome/free-solid-svg-icons@6.7.2/index.mjs",
    "@maplibre/vt-pbf": "https://cdn.jsdelivr.net/npm/@maplibre/vt-pbf@4.3.0/dist/index.es.js",
    "@mapbox/vector-tile": "https://cdn.jsdelivr.net/npm/@mapbox/vector-tile@2.0.4/index.js",
    "@photo-sphere-viewer/core": "https://cdn.jsdelivr.net/npm/@photo-sphere-viewer/core@5.14.1/index.module.js",
    "@photo-sphere-viewer/core/": "https://cdn.jsdelivr.net/npm/@photo-sphere-viewer/core@5.14.1/",
    "@photo-sphere-viewer/equirectangular-tiles-adapter": "https://cdn.jsdelivr.net/npm/@photo-sphere-viewer/equirectangular-tiles-adapter@5.14.1/index.module.js",
    "@photo-sphere-viewer/markers-plugin": "https://cdn.jsdelivr.net/npm/@photo-sphere-viewer/markers-plugin@5.14.1/index.module.js",
    "@photo-sphere-viewer/markers-plugin/": "https://cdn.jsdelivr.net/npm/@photo-sphere-viewer/markers-plugin@5.14.1/",
    "@photo-sphere-viewer/virtual-tour-plugin": "https://cdn.jsdelivr.net/npm/@photo-sphere-viewer/virtual-tour-plugin@5.14.1/index.module.js",
    "@photo-sphere-viewer/virtual-tour-plugin/": "https://cdn.jsdelivr.net/npm/@photo-sphere-viewer/virtual-tour-plugin@5.14.1/",
    "geojson-vt": "https://cdn.jsdelivr.net/npm/geojson-vt@4.0.2/src/index.js",
    "iconify-icon": "https://cdn.jsdelivr.net/npm/iconify-icon@3.0.2/dist/iconify-icon.mjs",
    "json5": "https://cdn.jsdelivr.net/npm/json5@2.2.3/dist/index.min.mjs",
    "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.2/index.js",
    "lit/": "https://cdn.jsdelivr.net/npm/lit@3.3.2/",
    "lit-html": "https://cdn.jsdelivr.net/npm/lit-html@3.3.2/lit-html.js",
    "lit-html/": "https://cdn.jsdelivr.net/npm/lit-html@3.3.2/",
    "lit-element/": "https://cdn.jsdelivr.net/npm/lit-element@4.2.2/",
    "maplibre-gl": "https://cdn.jsdelivr.net/npm/maplibre-gl@5.21.1/dist/maplibre-gl.js",
    "maplibre-gl/": "https://cdn.jsdelivr.net/npm/maplibre-gl@5.21.1/",
    "@fontsource/atkinson-hyperlegible-next/": "https://cdn.jsdelivr.net/npm/@fontsource/atkinson-hyperlegible-next@latest/",
    "pmtiles": "https://cdn.jsdelivr.net/npm/pmtiles@4.4.0/dist/esm/index.js",
    "@panoramax/web-viewer": "https://cdn.jsdelivr.net/npm/@panoramax/web-viewer/build/index.js",
    "@lit/reactive-element": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.1.2/reactive-element.js",
    "@mapbox/point-geometry": "https://cdn.jsdelivr.net/npm/@mapbox/point-geometry@1.1.0/index.js",
    "fflate": "https://cdn.jsdelivr.net/npm/fflate@0.8.2/esm/browser.js",
    "pbf": "https://cdn.jsdelivr.net/npm/pbf@4.0.1/index.js",
    "three": "https://cdn.jsdelivr.net/npm/three@0.179.1/build/three.module.js",
    "shadow-dom-selector": "https://cdn.jsdelivr.net/npm/shadow-dom-selector@6.1.0/dist/esm/index.js",
    "get-promisable-result": "https://cdn.jsdelivr.net/npm/get-promisable-result@2.0.0/dist/esm/index.js"
  }
}
</script>

Then, load the Panoramax module:

<script type="module" src="https://cdn.jsdelivr.net/npm/@panoramax/web-viewer@5.0.0/build/index.js"></script>

For your convenience, a bundled version is still available:

<script src="https://cdn.jsdelivr.net/npm/@panoramax/web-viewer@5.0.0/build/bundle.cjs"></script>

It was shorter, but heavier 🏋️

<link rel="stylesheet" type="text/css" href="web-viewer/build/index.css" />
<script src="web-viewer/build/index.js"></script>