Embedding Eximee Forms as a web component

The Eximee Forms presentation module can be run in the following variants:

• a standalone single page application hosted as a dedicated web page, embedded within a webview or iframe,

• a webcomponent library to embed in any existing web page or web application.

The forms application is functionally responsible for:

• presenting and handling forms defined via low-code in the Eximee platform,

• each form has a dynamic structure composed of components and one or more pages defined via low-code,

• Eximee forms manage the form state, handle user interactions and navigation within the presented form,

• the application can use navigation via the browser URL, using the fragment after # exclusively, or in-memory navigation that does not affect the browser URL state.

The documentation below describes how to embed and integrate Eximee forms using the webcomponent library.

General assumptions

To run a form:

• include the JavaScript files that provide the component implementations on the web page,

  • the component resources are served by the Eximee platform in a version compatible with the platform server,

  • the exact names and addresses of resources come from a manifest hosted together with other static platform files,

• ensure correct CORS and CSP headers between the Eximee platform domains and the host application,

  • in particular the ability to fetch static resources/assets of the forms application in the host application,

• ensure access to the Eximee platform REST API from the host application's domain,

• create the component DOM element from HTML or programmatically from JavaScript,

• initiate form loading via the programmatic JavaScript API.

Technologies used

The application is built using Angular version 20.x.x (subject to regular updates).

And it exposes a webcomponent according to the webcomponent specification in the scope of:

• custom elements,

• shadow dom.

The webcomponent can be embedded inside a Shadow DOM in open mode, however this must be taken into account when embedding DOM styles from the bundleStats.json manifest (described below).

Impact on the application's global execution context by zone.js

The application relies on the availability of a globally loaded zone.js library in a version compatible with the Angular version (and delivered with Angular/Angular CLI).

The zone.js library is fundamental to the operation of the Angular framework and is commonly used in applications built with it.

The library works by monkey-patching asynchronous browser APIs for user interactions to support UI change detection during user interactions.

The Eximee forms application is not currently adapted to run in a zoneless mode, and adapting it would require dedicated work on the Eximee platform side.

However, past experience shows that in the case of:

• using the webcomponent inside a host application that uses a compatible version of zone.js (e.g., written in Angular),

• using the webcomponent inside a host application that does not use zone.js (e.g., written in Vue or React).

We have not observed conflicts or operational issues with either of these host applications (host, Eximee). However, it is necessary to verify the compatibility of libraries embedded in the running application.

Impact on the application's global execution context by polyfills

The webcomponent library depends on the availability of (and includes, if not available) the following polyfills:

• core-js/shim from core-js,

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

• web-components/webcomponents-loader from polymer.

All polyfill dependencies comply with polyfill delivery standards, i.e.

• they do not overwrite native implementations available in the browser,

• they load only if they provide functionality not available natively and not provided by other means (e.g., by the host application),

• they are provided by commonly used open source libraries.

In practice, the indicated polyfills should not change behavior when:

• using modern browsers,

• used in a host application that uses modern web frameworks (e.g., Angular).

Resource manifest and release cycle

The webcomponent library resources depend on the current version of the Eximee platform deployed in a specific environment.

To simplify dependency management, the platform hosts a manifest file that describes the resources required to be included on the page to run the webcomponent.

The manifest is in JSON format and looks, for example, like:

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

Script and style resources should be loaded before running the form, e.g., by embedding them in script and link tags in the head section of the page where forms will be used.

All resource names contain content-based hashes. This makes it possible at the same time to:

• ensure loading the correct file consistent with the specific system version,

• reuse cached files if their content does not change between versions.

Resource embedding can be performed:

• dynamically by the application's frontend before starting the form,

• as part of server-side rendering of the host application's page (recommended method).

Note, when embedding the form webcomponent within nodes under a shadow DOM (open), it is necessary to embed links to styles inside the appropriate shadowRoot. Styles embedded in the document head will not be able to style the component inside the shadow DOM in the standard way.

Creating a form instance

Embedding the component and starting the form

The component can be embedded in the DOM using the component's HTML tag or programmatically using the JavaScript API:

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

The form component can be placed anywhere within the application's DOM structure.

After embedding and obtaining a reference to the element, it is possible to start the form using the loadForm method as in the example:

container.loadForm({
  formId: 'demoFormularzJakoWebcomponent', /* form identifier */
  baseHref: '/api',  /* path where the Eximee REST API is available through proxy-pass */
  onError: function () {
    alert('An error occurred while processing the application');
  }
});

It is possible to pass additional parameters to the loadForm method, which will be described in subsequent sections of the documentation and given in the reference API at the end of the document.

One such parameter is the ability to pass business parameters to start a specific form, for example:

container.loadForm({
  formId: 'demoFormularzJakoWebcomponent', /* form identifier */
  baseHref: '/api',  /* path where the Eximee REST API is available through proxy-pass */
  data: JSON.stringify({'param1': 'value1'}), /* Additional business parameters supplying the form as a JSON-stringified key-value object */
  onError: function () {
    alert('An error occurred while processing the application');
  }
});

Extending REST communication headers (including auth headers for API Gateway)

In many deployments it is necessary to extend headers of REST API requests, particularly in applications handling user authentication and relying on permission control at the API Gateway level (e.g., OIDC tokens).

To this end, it is possible to provide a function that will create headers to be attached to every REST request:

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

The header-creating method is called each time, directly before performing the request to the REST API. Headers are not stored between calls, which is particularly important for OAuth headers that may change as a result of token refresh during form handling.

Preserving form state between page refreshes / host application navigation

The complete form state and data entered by the user is stored on the Eximee platform server side within the user session.

This means it is possible to restore/resume a user's active form even after navigation within the host application or a full page refresh in the browser.

A user's form on the server is distinguished based on:

• the session identifier in a Cookie,

• the form instance identifier in the session based on the form instance number (formInstanceNumber).

Assuming Cookie handling is guaranteed and the Cookie is not removed (except when functional requirements demand such removal), restoring the form requires storing its instance number.

The form number can be passed to the loadForm method and retrieved from the instance after it starts. Assuming the host application has a consistent way to store this value (e.g., in the page query, server-side, etc.), it is possible to write:

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

Access to the Eximee platform REST infrastructure

The component presenting forms requires access to the REST API served by the Eximee platform instance. All REST API endpoints are already hosted and exposed for the standalone webforms instance (e.g., for web applications, embedding in webview or iframe).

The recommended solution (most often chosen by clients) is configuring a proxy pass in the host application's domain that forwards traffic to the Eximee infrastructure. This solution offers the simplest configuration from the infrastructure and security headers perspective and access control of the infrastructure because REST API calls are handled within the same domain in which the host page/application is presented.

Alternatively, it is possible to configure direct connections between the host application's domain and the Eximee REST server. However, this requires additional security/header configuration and verification by testing in specific environments.

It is also possible to develop another communication mechanism, in particular one where the host application intermediates every REST call. However, this requires analysis and designing a solution specific to the deployment and involves planning additional development work on the platform.

Forms application cookies

The application uses cookies describing:

• the user session,

• session affinity parameters for load balancers.

Cookies are created automatically by the server and infrastructure (load balancers) and are configured according to the parameters of the specific environment.

Known functional limitations

• The library assumes that only one form is presented on the screen at a time and attempting to display two concurrently running form instances may cause errors.

• Changing parameters of an initialized form requires reinitialization and means preparing a new instance (without data previously entered by the user).

Component interface

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'
}

Usage examples

The platform deployed in test environments hosts example HTML that embeds a form using the webcomponent:

• directly in the page DOM,

• wrapped in a Shadow Root.

Knowing the address of the Eximee platform, both examples can be viewed at https://[environment-address]/webcomponent/[deployment-skin]-webcomponent.html

HTML example:

<html>
<head>
    <script>
        /*  Method that starts the application directly in the DOM tree. */
        function initFormPlain() {
            // Preparing the component in the DOM tree
            const formWrapper = document.getElementById('form-wrapper');
            const formWebcomponent = document.createElement("ex-forms-form");
            formWrapper.appendChild(formWebcomponent);
 
            // Starting the form instance
            formWebcomponent.loadForm({
                formId: 'demoFormularzJakoWebcomponent',
                baseHref: '/api',
                onError: function () {
                    alert('An error occurred while processing the application');
                }
            });
        }
    </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>