capitec/omni-widget

vanilla-js web web-component widget

Omni Widget

@capitec/omni-widget

Framework agnostic, zero dependency web utilities to enable embedding externally hosted web content.

[Introduction] [Usage] [Contributors] [License]

Introduction

The <omni-widget> is a web component that makes hosting external web content easier, with bi-directional communication capabilities.
The Widget class exposes static functions to make it easier for hosted external web content to interact with its omni-widget host.

Usage

1️⃣ Install the library in your project.

npm install @capitec/omni-widget

For hosted widgets

2️⃣ Import the Widget class from the package and use relevant static functions for initialisation, event handling and messaging.

import { Widget } from '@capitec/omni-widget';

if (!Widget.isHosted) {
    console.log('Not hosted as a widget!');
} else {
    Widget.initialise(async function (identifier) {
        console.log(`Widget loaded with identifier: '${identifier}'`);
        const response = await Widget.messageApplicationAsync(Widget.currentIdentifier, 'some-event-from-the-widget', {
            message: 'This is event detail.'
        });
    });
    Widget.addEventListener('some-event-for-the-widget', async function (e) {
        console.log(`Widget message: '${JSON.stringify(e.content)}'`);
        e.callback('This is a response');
    });
}

For hosting widgets

2️⃣ Import the package

// JS import
import '@capitec/omni-widget';

// or HTML import
<script type="module" src="/node_modules/omni-widget/dist/index.js"></script>;

3️⃣ Use the web component to host the widget.

<omni-widget src="https://some-widget-url.html"></omni-widget>

4️⃣ Use instance functions on the component to send messages to the widget.

const widgetResponse = await document
    .querySelector('omni-widget')
    .messageWidgetAsync('some-event-for-the-widget', { message: 'This is event detail.' });

5️⃣ Use event listeners to receive messages from the widget.

document.querySelector('omni-widget').addEventListener('some-event-from-the-widget', function (e) {
    const widgetEventInfo = e.detail;
    console.log('Widget event data: ' + JSON.stringify(widgetEventInfo.content));
    widgetEventInfo.callback('This is a response.');
});