Osadzanie Eximee Forms jako webcomponent

Moduł prezentacji Formularzy platformy Eximee może być uruchomiony w wariancie:

• samodzielnej aplikacji single page application hostowanej jako dedykowana strona WWW, osadzona w ramach webview lub iframe,

• biblioteki webcomponentu do osadzenia w dowolnej istniejącej stronie lub aplikacji WWW.

Aplikacja formularzy funkcjonalnie odpowiada za:

• prezentację i obsługę formularzy zdefiniowanych za pomocą lowcode w platformie Eximee,

• każdy formularz ma dynamiczną strukturę składającą się z komponentów oraz jednej lub więcej stron definiowanych za pomocą lowcode,

• formularze Eximee zarządzają stanem formularza, obsługują interakcje użytkownika oraz nawigację w zakresie prezentowanego formularza,

• aplikacja może wykorzystywać nawigację przez URL przeglądarki, wykorzystując na wyłączność część za #, lub nawigację in-memory niewpływającą na stan URL przeglądarki.

Poniższa dokumentacja opisuje sposób osadzania i integracji formularzy Eximee za pomocą biblioteki webcomponentu.

Ogólne założenia

W celu uruchomienia formularza:

• należy dołączyć pliki JavaScript dostarczające implementacje komponentu do strony WWW,

  • zasoby komponentu są serwowane przez platformę Eximee w wersji zgodnej z serwerem platformy,

  • konkretne nazwy i adresy zasobów wynikają z metryczki hostowanej razem z innymi plikami statycznymi platformy,

• zapewnić poprawność nagłówków CORS i CSP pomiędzy domenami platformy Eximee a aplikacji hosta,

  • w szczególności możliwość pobierania zasobów statycznych/assetów aplikacji formularza w aplikacji hosta,

• zapewnić dostęp do API REST platformy Eximee z domeny aplikacji hosta,

• stworzyć element DOM komponentu z HTML lub, programowo, z JavaScript,

• zainicjować ładowanie formularza za pomocą programowego API z JavaScript.

Stosowane technologie

Aplikacja jest stworzona z użyciem Angular w wersji 20.x.x (podlega regularnym aktualizacjom).

Oraz eksponuje webcomponent zgodnie ze specyfikacją webcomponent w zakresie:

• custom elements,

• shadow dom.

Webcomponent może być osadzany wewnątrz Shadow DOM w trybie open, jednak konieczne jest uwzględnienie tego podczas osadzania w DOM styli z metryczki bundleStats.json (opisane niżej).

Wpływ na globalny kontekst wykonania aplikacji przez zone.js

Aplikacja polega na dostępności globalnie załadowanej biblioteki zone.js w wersji zgodnej z wersją Angular (i dostarczaną razem z Angular/Angular CLI).

Biblioteka zone.js jest podstawą działania frameworku Angular i jest powszechnie stosowana w aplikacjach w nim stworzonych.

Działanie biblioteki polega na monkey patchowaniu asynchronicznych API interakcji użytkownika ze stroną w celu obsługi detekcji zmian UI w ramach interakcji użytkownika.

Aplikacja formularzy Eximee nie jest obecnie dostosowana do pracy w trybie zoneless, a ew. adaptacja wymagałaby dedykowanych prac po stronie platformy Eximee.

Dotychczasowe doświadczenia pokazują jednak, że w przypadku:

• stosowania webcomponentu wewnątrz aplikacji hosta używającej zgodnej wersji zone.js (np. napisanej w Angular),

• stosowania webcomponentu wewnątrz aplikacji hosta nieużywającej zone.js (np. napisanej w vue czy react).

Nie obserwowaliśmy konfliktów ani problemów z działaniem z żadnej z tych aplikacji (hosta, Eximee). Należy jednak mieć na uwadze konieczność weryfikacji kompatybilności bibliotek osadzonych w działającej aplikacji.

Wpływ na globalny kontekst wykonania aplikacji przez polyfills

Biblioteka webcomponentu polega na dostępności (oraz dołącza, jeśli nie są dostępne) polyfills:

• core-js/shim z core-js,

• @webcomponents/webcomponentsjs/custom-elements-es5-adapter.js z @webcomponents/webcomponentsjs,

• web-components/webcomponents-loader z polymer.

Wszystkie zależności polyfills są zgodne ze standardami dostarczania polyfilii, tj.

• nie nadpisują natywnych rozwiązań dostępnych w przeglądarce,

• ładują się, tylko jeżeli dostarczają funkcjonalność niedostępną natywnie i niedostarczoną innymi metodami (np. przez aplikację hosta),

• są dostarczane przez powszechnie stosowane biblioteki open source.

W praktyce wskazane polyfills nie powinny zmieniać zachowania w przypadku:

• stosowania nowoczesnych przeglądarek,

• stosowania w aplikacji hosta używającej nowoczesnych frameworków web (jak np. Angular).

Metryczka zasobów i cykl wydań

Zasoby biblioteki webcomponentu są zależne od aktualnej wersji platformy Eximee osadzonej na konkretnym środowisku.

W celu łatwego zarządzania zależnościami platforma hostuje plik metryczki opisujący zasoby wymagane do dołączenia do strony w celu uruchomienia webcomponentu.

Metryczka jest w formacie JSON i przykładowo wygląda:

{
  "format": 3,
  "scripts": [
    "polyfills.125595b8f8d58bce.js",
    "main.922b3d09b697675a.js"
  ],
  "styles": [
    "styles.6e50ddf23fe0e270.css"
  ]
}

Zasoby skryptów i styli należy załadować przed uruchomieniem formularza, np. przez osadzenie w tagach script i link w części head strony, na której będą używane formularze.

Wszystkie nazwy zasobów zawierają hashe na podstawie treści plików. Dzięki temu możliwe jest równocześnie:

• zapewnienie ładowania odpowiedniego pliku zgodne z konkretną wersją systemu,

• reużywanie plików z cache, jeżeli pomiędzy wersjami ich treść się nie zmienia.

Osadzenie zasobów może być realizowane:

• dynamicznie przez frontend aplikacji przed uruchomieniem formularza,

• w ramach server side renderingu strony hostującej aplikację hosta (zalecany sposób).

Uwaga, w przypadku osadzenia webcomponentu formularza w ramach węzłów za shadow dom (open) konieczne jest osadzanie linków do styli wewnątrz odpowiedniego shadowRoot. Style osadzone w head całego dokumentu nie będą mogły standardowo ostylować komponentu wewnątrz shadow dom.

Tworzenie instancji formularza

Osadzanie komponentu i uruchamianie formularza

Komponent można osadzić w DOM za pomocą tagu HTML komponentu lub programowo za pomocą API JavaScript:

var form = document.createElement("ex-forms-form");
document.body.appendChild(form)

Komponent formularza może być osadzony w dowolnym miejscu w strukturze DOM aplikacji.

Po osadzeniu i otrzymaniu referencji na element możliwe jest uruchomienie formularza metodą loadForm zgodnie z przykładem:

container.loadForm({
  formId: 'demoFormularzJakoWebcomponent', /* identyfikator formularza */
  baseHref: '/api',  /* path, po którym dostępne jest REST API Eximee udostępnione przez proxy-pass */
  onError: function () {
    alert('Wystąpił błąd podczas procesowania wniosku');
  }
});

Istnieje możliwość przekazania dodatkowych parametrów do metody load form, co zostanie opisane w kolejnych sekcjach dokumentacji oraz podane w referencyjnym API na końcu dokumentu.

Jednym z takich parametrów jest możliwość przekazania biznesowych parametrów uruchomienia konkretnego formularza, przykładowo:

container.loadForm({
  formId: 'demoFormularzJakoWebcomponent', /* identyfikator formularza */
  baseHref: '/api',  /* path po którym dostępne jest REST API Eximee udostępnione przez proxy-pass */
  data: JSON.stringify({'param1': 'value1'}), /* Dodatkowe parametry biznesowe zasilające formularz w postaci serializowanego do JSON string obiektu klucz-wartość  */
  onError: function () {
    alert('Wystąpił błąd podczas procesowania wniosku');
  }
});

Rozszerzanie nagłówków komunikacji REST (w tym nagłówki auth dla API Gateway)

W wielu wdrożeniach zachodzi konieczność rozszerzenia nagłówków żądań REST API, w szczególności w aplikacjach obsługujących uwierzytelnianie użytkownika i polegających na kontroli uprawnień na poziomie API Gateway (np. tokenami OIDC).

W tym celu możliwe jest wskazanie funkcji tworzącej nagłówki, które zostaną dołączone do każdego żądania REST:

form.loadForm({
    formId: 'demoFormularzJakoWebcomponent',
    additionalRequestHeaders: () => ({
        'X-Custom-Header': 'value'
    })
})

Metoda tworząca nagłówki jest wywoływana za każdym razem, bezpośrednio przed wykonanie żądania do REST API. Nagłówki nie są przechowywane pomiędzy wołaniami, co jest szczególnie istotne np. dla nagłówków Oauth, które mogą się zmienić w wyniku odświeżania tokenu w trakcie obsługi formularza.

Zachowywanie stanu formularza pomiędzy odświeżeniami strony / nawigacją aplikacji hosta

Kompletny stan formularza i danych wprowadzonych przez użytkownika jest przechowywane po stronie serwera platformy Eximee w ramach sesji użytkownika.

Oznacza to, że istnieje możliwość odtworzenia/wznowienia aktywnego formularza użytkownika nawet po nawigacji w aplikacji hosta lub całkowitym odświeżeniu strony w przeglądarce.

Formularz użytkownika po stronie serwera jest rozróżniany na podstawie:

• identyfikatora sesji w Cookie,

• identyfikatora instancji formularza w sesji na podstawie numeru instancji formularza (formInstanceNumber).

Zakładając, że obsługa Cookie jest zagwarantowana oraz Cookie nie zostanie usunięte (poza sytuacją, gdy wymagania funkcjonalne wymagają takiego usunięcia) to do odtworzenia formularza konieczne jest przechowanie jego numer instancji.

Numer formularza można przekazać do metody load form oraz pobrać z instancji po jego uruchomieniu. Zakładając, że aplikacja hosta posiada jednoznaczny sposób przechowania tej wartości (np. w query strony, serwerowo itp.), możliwe jest napisanie:

let formInstanceNumber: string | undefined = restoreFormInstanceNumber();
form.loadForm({
    formId: 'demoFormularzJakoWebcomponent',
    formInstanceNumber: formInstanceNumber,
    onLoaded: (result, config) => storeFormInstanceNumber(result.data.formModel.formNumber),
});

Dostęp do infrastruktury REST platformy Eximee

Komponent prezentujące formularze wymaga dostępu do REST API serwowanego przez instancję platformy Eximee. Wszystkie endpointy REST API są już hostowane i eksponowane na potrzeby instancji samodzielnej webforms (np. na potrzeby aplikacji www, osadzania webview czy iframe).

Zalecanym rozwiązaniem (najczęściej wybieranym przez klientów) jest konfiguracja proxy pass w domenie aplikacji hosta przekazująca ruch do infrastruktury Eximee. To rozwiązanie oferuje najprostszą konfigurację od strony infrastruktury i nagłówków bezpieczeństwa oraz kontroli dostępu do infrastruktury ze względu na obsługę REST API w ramach tej samej domeny, w ramach której prezentowana jest strona / aplikacja hosta.

Alternatywnie, możliwa jest konfiguracja z połączeniami bezpośrednio pomiędzy domenami aplikacji hosta a serwerem REST Eximee. To wymaga jednak dodatkowej konfiguracji bezpieczeństwa/nagłówków oraz weryfikacji testami poszczególnych środowisk.

Możliwe jest również wypracowanie innego mechanizmu komunikacji, w szczególności takiego, w którym aplikacja hosta pośredniczy w każdym wywołaniu REST. Jednak wymaga to analizy i wypracowania konkretnego dla danego wdrożenia rozwiązania i wiąże się z zaplanowanie dodatkowych prac rozwojowych w platformie.

Cookie aplikacji formularza

Aplikacja wykorzystuje cookie opisujące:

• sesję użytkownika,

• parametry session affinity dla loadbalancerów.

Cookie są tworzone automatycznie przez serwer i infrastrukturę (loadbalancery) i są skonfigurowane zgodnie z parametrami konkretnego środowiska.

Znane ograniczenia funkcjonalne

• Biblioteka zakłada, że na jednym ekranie równocześnie prezentowany jest tylko jeden formularz i próba wyświetlenia dwóch równolegle działających instancji formularzy może powodować błędy.

• Zmiana parametrów zainicjowanego formularza wymaga jego ponownej inicjalizacji i oznacza przygotowanie nowej instancji (bez dotychczas wprowadzonych przez użytkownika danych).

Interfejs komponentu

export interface FormWebcomponentApi {
    loadForm(config: LoadFormConfig): void;
    hasActiveForm(): boolean;
 
    cancelCurrentForm(): void;
    handleAction(action: ExAction): void;
    proceedCurrentForm(): void;
    backCurrentForm(): void;
    isLastVisiblePage(): boolean;
    isFirstVisiblePage(): boolean;
    shouldShowForwardButton(): boolean;
    shouldShowBackwardButton(): boolean;
    getForwardButtonLabel(): string;
    onShowSpinner(callback: () => void): void;
    onHideSpinner(callback: () => void): void;
    getTranslation(key: string): string;
}
 
export interface LoadFormConfig extends LoadConfig {
    formId: string;
}
 
export interface LoadConfig {
    formInstanceNumber?: string;
    processId?: string;
    baseHref?: string;
    accessToken?: string;
    tokenType?: string;
    readonly?: boolean;
    data?: string;
    shadowRoot?: ShadowRoot;
    scrollOnErrorOffset?: number;
    additionalRequestHeaders?: () => { [header: string]: string };
    onLoaded?: (result: unknown, config: LoadConfig) => void;
    onActionDispatched?: (result: unknown, config: LoadConfig) => void;
    onCancelled?: (config: LoadConfig) => void;
    onSaved?: (result, config: LoadConfig) => void;
    onDraftSaved?: (result, config: LoadConfig) => void;
    onPageChanged?: (result, config: LoadConfig) => void;
    onModelChanged?: (result, config: LoadConfig) => void;
    onPageValidationErrors?: (result, config: LoadConfig) => void;
    onError?: (error, config: LoadConfig) => void;
    onAppEvent?: (event, config: LoadConfig) => void;
    onComponentValueChanged?: (result: unknown, config: LoadConfig) => void;
    onShowSpinner?: (immediate: boolean ) => void;
    onHideSpinner?: () => void;
}
 
export interface ExAction {
    sourceId: string;
    event: ExActionEvent | string;
    detail?: object | string | number | boolean;
}
 
export enum ExActionEvent {
    SAVE = 'SAVE',
    CLOSE = 'CLOSE',
    NEXT = 'NEXT',
    EDIT = 'EDIT',
    CLICK_MORE_INFO = 'CLICK_MORE_INFO',
    CALL = 'CALL',
    CHECK = 'CHECK',
    UNCHECK = 'UNCHECK',
    CLICK = 'CLICK',
    ON_EXIT = 'ON_EXIT',
    TOOLTIP_CLICKED = 'TOOLTIP_CLICKED',
    AUTOCOMPLETE_NO_MATCH_BUTTON_CLICKED = 'AUTOCOMPLETE_NO_MATCH_BUTTON_CLICKED',
    EXPAND_STATEMENT = 'EXPAND_STATEMENT',
    ON_PAGE_ENTER = 'ON_PAGE_ENTER',
    POI_SELECTED = 'POI_SELECTED',
    HIDDEN = 'HIDDEN',
    CLOSE_POPUP = 'CLOSE_POPUP',
    RETRY = 'RETRY',
    SAVE_DRAFT = 'SAVE_DRAFT',
    VALUE_CHANGED = 'VALUE_CHANGED',
    FORWARD_PAGE = 'FORWARD_PAGE',
    BACKWARD_PAGE = 'BACKWARD_PAGE',
    PARK_FORM_WITH_PROVIDED_HASH = 'PARK_FORM_WITH_PROVIDED_HASH',
    SHOW_POPUP = 'SHOW_POPUP',
    SAVE_POPUP = 'SAVE_POPUP',
    TOGGLE = 'TOGGLE',
    CLEAR_UPLOAD_FILE = 'CLEAR_UPLOAD_FILE',
    REDIRECT_TO_RETURN_URL = 'REDIRECT_TO_RETURN_URL',
    REDIRECT = 'REDIRECT',
    CHECK_FED_STATEMENT = 'CHECK_FED_STATEMENT',
    POPUP_SAVED = 'POPUP_SAVED',
    POPUP_HIDDEN = 'POPUP_HIDDEN',
    START_PROCESS = 'START_PROCESS',
    COMPLETE_USER_TASK = 'COMPLETE_USER_TASK',
    TILE_CLICKED = 'TILE_CLICKED',
    START_APPLICATION = 'START_APPLICATION',
    EXIT_CONFIRMED = 'EXIT_CONFIRMED'
}

Przykłady użycia

Platforma wdrażana na środowiskach testowych hostuje przykładowy HTML osadzający formularz za pomocą webcomponentu:

• bezpośrednio w DOM strony,

• opakowany w Shadow Root.

Znając adres platformy Eximee, oba przykłady można obejrzeć pod adresem https://[adres-srodowiska]/webcomponent/[szata-wdrozenia]-webcomponent.html

Przykład HTMLa:

<html>
<head>
    <script>
        /*  Metoda uruchamiająca wniosek bezpośrednio w drzewie DOM. */
        function initFormPlain() {
            // Przygotowanie komponentu drzewie DOM
            const formWrapper = document.getElementById('form-wrapper');
            const formWebcomponent = document.createElement("ex-forms-form");
            formWrapper.appendChild(formWebcomponent);
 
            // Uruchomienie instancji formularza
            formWebcomponent.loadForm({
                formId: 'demoFormularzJakoWebcomponent',
                baseHref: '/api',
                onError: function () {
                    alert('Wystąpił błąd podczas procesowania wniosku');
                }
            });
        }
    </script>
</head>
<body>
    <div id="form-wrapper"></div>
    <script src="polyfills.5310c9e539f37fb1.js" type="module"></script>
    <script src="main.71e5244a2a4d4f3d.js" type="module"></script>
</body>
</html>