Migrating to ESM
What’s new in HOOPS Communicator
This document is intended to describe the differences between HC version 24.2.0 and previous versions, especially related to ESM. For an overview of ESM, see our page on ESM.
What is in the box?
Everything ESM related is located in the <COMMUNICATOR_INSTALL_DIR/web_viewer directory of the package. In this directory you will find the following content:
The engine
engine.esm.js
engine.esm.wasm
The Web Viewer
hoops-web-viewer.mjs - This file contains the Web Viewer’s code as an ES Module
hoops-web-viewer.iife.mjs - This file is equivalent to hoops_web_viewer.js file in versions prior to 24.2.0
hoops-web-viewer.umd.js - This file contains the Web Viewer’s code as an UMD, it can be loaded through RequireJS.
Note
As you can see, the naming convention has slightly changed to follow Node.js recommendations.
The Monolithic Web Viewer
hoops-web-viewer-monolith.mjs
hoops-web-viewer-monolith.iife.mjs
hoops-web-viewer-monolith.umd.js
Another advantage of moving to ESM is that the monolithic version of the code is also available in three versions.
> A types directory containing the type declarations
> An examples directory which contains the developer samples, it is equivalent to web_viewer/examples but using ES Modules.
> A demo-app directory which contains the code of our demo application, it is equivalent to web_viewer/src but slightly different.
You will also notice that applications directory names has also changed in order to follow MDN recommendations.
The js directories are now named scripts.
Aside from the new file and directory names you will notice that the demo app code is not bundled into js/web_viewer_ui.js. The entire code is now written in humanly readable Javascript (it is transpiled from Typescript unminified and unbundled) in web_viewer/demo-app/web-viewer-demo/src so you can navigate the code. This is equivalent to web_viewer/typescript/ui, but implemented using ES Modules
General API changes for 24.2.0
Every Web Viewer API deprecated prior to HC 24.2.0 has been removed.
The path to the engine’s directory is now necessary to load your engine.esm.js and engine.esm.wasm.
Due to the different way to integrate the Web Viewer library into your application there is no solution that would satisfy everyone. In many cases,
document.currentScript
would be null,import.meta.url
would not be supported or it may not point to the appropriate location, etc. Therefore, it is now required for the user to set theenginePath
when creating aWebViewer
object.However, it can be handy not to have to set the
enginePath
on construction. In this case, you can set thedefaultEnginePath
on theWebViewer
class then whenever you instantiate aWebViewer
without specifying theenginePath
, it will use thedefaultEnginePath
to locate the engine’s files.
ESM-specific API changes
If you are using ESM there is no need for you to prefix the components you need with Communicator
. For example:
import { WebViewer } from 'hoops-web-viewer.mjs';
const hwv = new WebViewer({
// ...
});
However, you can still use the Communicator prefix using aliased import:
import * as Communicator from 'hoops-web-viewer.mjs';
const hwv = new Communicator.WebViewer({
// ...
});
Communicator.Operator is now Operators.
import { Operators } from 'hoops-web-viewer.mjs';
// ...
const op = new Operators.AxisTriadOperator(/* ... */);
BCF-related objects are now under Bcf
namespace.
import { Bcf } from 'hoops-web-viewer.mjs';
// ...
const markup = new Bcf.BCFMarkup(/* ... */);
Floorplan-related objects are now under Floorplan
namespace.
import { Floorplan } from 'hoops-web-viewer.mjs';
// ...
const fp = new Floorplan.FloorplanConfig(/* ... */);