Skip to content

Developing on the client

You want to work on our library and offer bug fixes or new features ? That's awesome ! 🤩

Here are some inputs about working with Panoramax web client code.

Note

If something seems missing or incomplete, don't hesitate to contact us by email or using an issue. We really want Panoramax to be a collaborative project, so everyone is welcome (see our code of conduct).

Architecture

The current code is split between various elements:

  • Core components: a single functional entry, like Viewer (map + picture), Photo Viewer (picture only), Coverage Map or Editor. They share parts of code in Basic class. They specialized the behaviour of components depending on the needs.
  • UI components, menus & widgets: reusable web components, like Map, Photo or Loader. They are used in some views depending of the context.
  • Utils: utility functions, splitted in various files for clarity.

Class diagram of Panoramax web viewer

The library is relies on various other libraries:

Good to know

Components z-index

In order to offer a coherent overlay of widgets, we follow this general z-index ordering:

Component type Z-Index
MapLibre GL & Photo Sphere Viewer <= 110
Widgets / Cornered Grid's corners 120
Togglable menus 130
Fullscreen loaders & popups 200

Parameters handling

Note

This concerns only Viewer component. Editor & Coverage Map read input parameters only from Web Components attributes.

Viewer component can read parameters from 3 different sources:

  • Web Component attributes, passed through DOM
  • Browser local storage
  • URL search parameters

This allows a flexible way to interact with viewer for users. Prioritization of parameters is managed by InitParameters class, URL parameters coming first, then local storage, to fallback with Web component attributes (and eventually some hard-coded defaults).

This means that, when developing, if you want to check if your attributes are well-defined, you may want to get rid of URL search parameters, as well as remove the pnx-map-parameters local storage item. Otherwise, they may not be read as they are lower priority than others.

Testing

We're trying to make Panoramax as reliable and secure as possible. To ensure this, we rely heavily on code testing. A variety of testing tools is made available:

  • npm start : launches a dev web server on localhost:3000
  • npm run test : unit testing
  • npm run lint : syntax checks
  • npm run coverage : amount of tested code

If you're working on bug fixes or new features, please make sure to add appropriate tests to keep Panoramax level of quality.

Documentation

The documentation is a mix of:

  • JSDoc comments embed directly in source files, and exported in docs/reference/ folder
  • Higher-level docs as Markdown files, in docs/ folder.

The JSDoc can be exported as Markdown using this command:

npm run doc

And all documentation can be previewed or built using Mkdocs:

pip install mkdocs mkdocs-material
mkdocs serve
mkdocs build

Online versions are available at:

Make a release

See dedicated documentation.