:orphan:

################
Migrating to ESM
################

What's new in |HCNOW| 
======================

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 :doc:`ESM </overview/esm>`.


What is in the box?
===================

Everything ESM related is located in the *<INSTALL_DIR/web_viewer* directory of the package. In this directory you will find the following content:

**The engine**

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

.. admonition:: 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 <https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/Dealing_with_files>`_.

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 *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 the ``enginePath`` when creating a ``WebViewer`` object.

  However, it can be handy not to have to set the ``enginePath`` on construction. In this case, you can set the ``defaultEnginePath`` on the ``WebViewer`` class then whenever you instantiate a ``WebViewer`` without specifying the ``enginePath``, it will use the ``defaultEnginePath`` 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:

.. code-block:: typescript

	import { WebViewer } from 'hoops-web-viewer.mjs';

	const hwv = new WebViewer({
	  // ...
	});

However, you can still use the Communicator prefix using aliased import:

.. code-block:: typescript

	import * as Communicator from 'hoops-web-viewer.mjs';

	const hwv = new Communicator.WebViewer({
	  // ...
	});

`Communicator.Operator` is now `Operators`.

.. code-block:: typescript

	import { Operators } from 'hoops-web-viewer.mjs';

	// ...

	const op = new Operators.AxisTriadOperator(/* ... */);

BCF-related objects are now under ``Bcf`` namespace.

.. code-block:: typescript

	import { Bcf } from 'hoops-web-viewer.mjs';

	// ...

	const markup = new Bcf.BCFMarkup(/* ... */);


Floorplan-related objects are now under ``Floorplan`` namespace.

.. code-block:: typescript

	import { Floorplan } from 'hoops-web-viewer.mjs';

	// ...

	const fp = new Floorplan.FloorplanConfig(/* ... */);
