Używanie ORBITVU VIEWER jako modułu ES

Od wersji VIEWER 3.10.19 każdy pakiet ORBITVU VIEWER zawiera drugi bundle obok klasycznego:

orbitvu12/
  orbitvu.js        # klasyczny bundle — wczytywany za pomocą znacznika <script>
  orbitvu.esm.js    # bundle w formie modułu ES — importowany
  viewer5.css       # arkusz stylów — musi być wczytany osobno przez konsumentów modułu ES
  version.xml
  LICENSE.txt

Oba bundle są budowane z tego samego źródła i renderują się identycznie. Różnica polega na sposobie, w jaki Twoja strona się do nich dostaje: orbitvu.js musi zostać wczytany za pomocą znacznika <script>, zanim będzie można go wywołać, natomiast orbitvu.esm.js jest importowany — co jest rozwiązaniem właściwym, jeśli Twoja strona jest budowana za pomocą Vite, webpack, Rollup, Next.js lub innego bundlera.

mount_viewer

Moduł eksportuje jedną funkcję. Zaimportuj arkusz stylów razem z nią — viewer5.css nie jest częścią bundle'a, a bez niego prezentacja wyświetli się bez stylów:

import { mount_viewer } from './orbitvu12/orbitvu.esm.js';
import './orbitvu12/viewer5.css';   // wymagane — patrz poniżej

const viewer = mount_viewer(containerId, params);

mount_viewer montuje przeglądarkę w elemencie o podanym id i zwraca instancję przeglądarki. params to ten sam obiekt parametrów VIEWER, który przyjmuje klasyczny bundle, łącznie z width i height, które przyjmują tam te same wartości, co wszędzie indziej — 'auto', zwykłą liczbę lub wartość z jednostką.

Warto pamiętać o dwóch rzeczach:

• Element kontenera musi istnieć wcześniej. mount_viewer wyszukuje go po id i wypełnia go zawartością; nie tworzy go.
• Samo zaimportowanie modułu niczego nie uruchamia, więc można go bezpiecznie zaimportować w buildzie renderowanym po stronie serwera. Montowanie wymaga prawdziwego DOM — wywołuj mount_viewer tylko w przeglądarce.

Gdy przeglądarka nie jest już potrzebna — w cleanupie hooka useEffect w React lub przy zmianie trasy przez router — wywołaj destroy() na zwróconej wcześniej instancji:

viewer.destroy();

Wczytywanie arkusza stylów

viewer5.css jest osobnym plikiem, a nie czymś wbudowanym w bundle, dzięki czemu wstrzyknięty element <style> nie może naruszyć restrykcyjnej konfiguracji Content-Security-Policy. Import orbitvu.esm.js nie pociąga więc za sobą żadnych stylów, a stylów tych możesz dostarczyć na trzy sposoby:

1. Zaimportuj go obok bundle'a — preferowany sposób i jedyny, który nie powoduje pierwszego niestylizowanego renderowania:

   import { mount_viewer } from '../vendor/orbitvu12/orbitvu.esm.js';
   import '../vendor/orbitvu12/viewer5.css';

2. Podlinkuj go ze strony hosta:

   <link rel="stylesheet" href="https://twojadomena.com/orbitvu12/viewer5.css" />

3. Przekaż viewer_base i pozwól, aby VIEWER sam dołączył znacznik <link> w momencie montowania:

   mount_viewer('presentation1-container', {
       viewer_base: 'https://twojadomena.com/orbitvu12/',
       // …
   });

   Wczytanie arkusza stylów to jedyne, co robi viewer_base — jeśli dostarczyłeś go już jednym z powyższych sposobów, ten parametr w ogóle nie jest potrzebny.

Podstawowy przykład

<!DOCTYPE html>
<html lang="pl">
    <head>
        <meta charset="UTF-8" />
        <title>Prezentacja Orbitvu</title>
        <link rel="stylesheet" href="https://twojadomena.com/orbitvu12/viewer5.css" />
    </head>
    <body>
        <div id="presentation1-container"></div>

        <script type="module">
            import { mount_viewer } from 'https://twojadomena.com/orbitvu12/orbitvu.esm.js';

            mount_viewer('presentation1-container', {
                ovus_folder: 'https://twojadomena.com/presentations/presentation1/',
                content2: 'yes',
                width: '500',
                height: '400'
            });
        </script>
    </body>
</html>

Użycie z bundlerem

Skopiuj folder orbitvu12/ do swojego projektu (lub udostępnij go z własnego hostingu statycznego) i zaimportuj bundle jak każdy inny moduł, tak aby VIEWER trafił do Twojego własnego pipeline'u zasobów.

import { mount_viewer } from '../vendor/orbitvu12/orbitvu.esm.js';
import '../vendor/orbitvu12/viewer5.css';

export function showPresentation(containerId, presentationUrl) {
    return mount_viewer(containerId, {
        ovus_folder: presentationUrl,
        content2: 'yes',
        width: 'auto',
        height: 'auto',
        teaser: 'autorotate'
    });
}

Dostęp do API

mount_viewer zwraca instancję przeglądarki od razu, ale obiekt VIEWER API jest tworzony później, dopiero gdy załadują się pliki konfiguracyjne prezentacji — więc odczytanie go ze zwróconej instancji nie zadziała. Zamiast tego przekaż viewer_api_init, podając mu samą funkcję: callback nazwany za pomocą stringa jest wyszukiwany w globalnym zasięgu strony, do którego funkcja zdefiniowana wewnątrz modułu nie ma dostępu.

viewer_api_init uruchamia się wcześnie, zanim zostanie zażądana pierwsza klatka. Obiekt API jest w tym momencie kompletny, ale przeglądarka nie jest jeszcze gotowa do sterowania — obracanie, powiększanie i przesuwanie nic nie robią, dopóki klatki nie zostaną wczytane. Użyj więc viewer_api_init do zarejestrowania swoich callbacków, a steruj przeglądarką ze zdarzenia viewer_initialized, które przekazuje ten sam obiekt API, gdy prezentacja jest już gotowa:

import { mount_viewer } from '../vendor/orbitvu12/orbitvu.esm.js';
import '../vendor/orbitvu12/viewer5.css';

let viewerApi = null;

function onViewerReady(api) {
    viewerApi = api;
    api.setScene({ hangle: 10 });   // bezpieczne tutaj — przeglądarka jest już załadowana
}

const viewer = mount_viewer('presentation1-container', {
    ovus_folder: '/presentations/presentation1/',
    content2: 'yes',
    width: 'auto',
    height: '400px',
    viewer_api_init: (api) => {
        api.addCallback(onViewerReady, 'viewer_initialized');
    }
});

addCallback(callback, event_name) przyjmuje też referencję do funkcji, więc nic w tym przepływie nie wymaga globalnie nazwanej funkcji.

Różnice względem klasycznego bundle'a

inject_orbitvu nie jest częścią bundle'a modułowego — przy przenoszeniu osadzenia na import, zastąp go funkcją mount_viewer, która nie przyjmuje argumentu folderu VIEWER i pobiera wszystko inne z tego samego obiektu params.