Skip to content

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.

// 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.

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

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>