Migration from v3 to v4

The version 4 of Panoramax Web Viewer has seen major changes, migrating from custom code to Web Components. This requires you to change a few things compared to version 3.

Note

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

🪄 Initializing components

The way you create a component (viewer, editor, coverage map) is different :

v4v3

Now, you have to create a HTML-like component and pass attributes.

<pnx-viewer id="myviewer" endpoint="https://api.panoramax.xyz/api" />

You can then access it in JS to manage it.

let myviewer = document.getElementById("myviewer");

Also note that custom MapLibre style must be passed as mapstyle attribute.

Before, you created a div with ID, then passed it to JS class.

let myViewer = new Panoramax.Viewer("viewer", "https://api.panoramax.xyz/api");

And MapLibre style was passed as a style property in option object.

⏯️ Widgets options

Viewer widgets options are managed quite differently in version 4:

You can disable all widgets with widgets="false" map="false" options
You can add or replace widgets using web component slots (insert your own widgets as child of viewer)

This allows to do things like:

<pnx-viewer
  endpoint="https://panoramax.openstreetmap.fr/"
  widgets="false"
>
  <p slot="top-right">My custom text</p>
</pnx-viewer>

This offers more flexibility, check out how to manage custom widgets in dedicated documentation.

🏷️ Class & packages names

Many stuff was moved around, and have a bit different naming. Main classes should be called directly by their web component name:

v3 class	v4 web component
`Panoramax.Viewer`	`<pnx-viewer>`
`Panoramax.Editor`	`<pnx-editor>`
`Panoramax.StandaloneMap`	`<pnx-coverage-map>`

A new main component is available, named Photo Viewer (<pnx-photo-viewer>) for showing up only picture (without map).

And source code is splitted in more packages:

Panoramax.components : everything you can see graphically
- .core : Viewer, Editor, Coverage Map and Basic (common code)
- .layout : helper classes for layout
- .menus : complex menus (map filters, picture metadata...)
- .ui : re-usable small graphical components
- .ui.widgets : specialized small graphical components (button + menu, extended search bar...)
Panoramax.utils : helper classes and functions

👂 Events

Many events names were changed, and some of them moved to sub-components.

v3 class	v3 event name	v4 class	v4 event name
CoreView	`map:background-changed`	components.ui.Map	`background-changed`
CoreView	`map:picture-click`	components.ui.Map	`picture-click`
CoreView	`map:sequence-hover`	components.ui.Map	`sequence-hover`
CoreView	`map:sequence-click`	components.ui.Map	`sequence-click`
CoreView	`map:users-changed`	components.ui.Map	`users-changed`
CoreView	`psv:picture-loaded`	components.ui.Photo	`picture-loaded`
CoreView	`psv:picture-loading`	components.ui.Photo	`picture-loading`
CoreView	`psv:picture-preview-started`	components.ui.Photo	`picture-preview-started`
CoreView	`psv:picture-preview-stopped`	components.ui.Photo	`picture-preview-stopped`
CoreView	`psv:picture-tiles-loaded`	components.ui.Photo	`picture-tiles-loaded`
CoreView	`psv:view-rotated`	components.ui.Photo	`view-rotated`
CoreView	`psv:transition-duration-changed`	components.ui.Photo	`transition-duration-changed`
Viewer	`filters-changed`	components.ui.MapMore	`filters-changed`
Viewer	`focus-changed`	components.core.Viewer	`focus-changed`
Viewer	`josm-live-enabled`	❌ Removed
Viewer	`josm-live-disabled`	❌ Removed
Viewer	`pictures-navigation-changed`	components.ui.Photo	`pictures-navigation-changed`
Viewer	`sequence-playing`	components.ui.Photo	`sequence-playing`
Viewer	`sequence-stopped`	components.ui.Photo	`sequence-stopped`

To listen to these events, you can use map and psv properties of your component.

myviewer.addEventListener("focus-changed", e => console.log(e));
myviewer.psv.addEventListener("sequence-playing", e => console.log(e));

// Note that MapLibre uses on/once functions for events
myviewer.map.on("picture-click", e => console.log(e));

To make use of these sub-components events easier, note that you can also call them from parent component using the property name as a prefix. For example:

// Transfers listener to map sub-component
myviewer.addEventListener("map:moveend", e => console.log(e));

// Works for any sub-component, like URL Handler or PSV
myviewer.addEventListener("urlHandler:url-changed", e => console.log(e));
myviewer.addEventListener("psv:picture-loaded", e => console.log(e));

To know more about available events per component, please refer to their individual API page.

⚙️ Functions

Many functions were changed as well, in order to reduce source files size and make things more logical. You can find all API reference in this doc, here's a summary:

v3	v4
`Viewer.refreshPSV`	`(components.ui).Photo.forceRefresh`
`Viewer`'s play/stop/toggle sequence	Gone to `(components.ui).Photo`
`Viewer`'s get/set pictures navigation	Gone to `(components.ui).Photo`
`Viewer.toggleJOSMLive`	Made private in `(components.ui.widgets).Share`
`Viewer`'s set/toggle focus/unfocused	Managed through `(components.core).Viewer` `focus` attribute and `mini` property
`Viewer.setFilters`	`(components.ui).MapMore`

🌍 URL parameters

URL parameters are now managed in the URL search part (everything after the ?), whereas in version 3 it was managed through hash part (everything after the #). To ensure long-term compatibility, you may just replace the # in your URL by ?. Here's an example of these new URL:

https://panoramax.ign.fr/?background=streets&focus=map&map=9/48.6659/2.3237&speed=250

🪛 Initialization parameters

Parameters passed to Viewer are more finely read, they can come from Web Component itself (attributes), browser local storage or URL search parameters. URL ones are read first, then local storage, and finally component attributes. This can be misleading while you develop, read more about this on Develop documentation.