capitec/omni-widget

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

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.');
});

🚩 Example Usage Project

An example project is available in the example directory.

Contributors

Made possible by these fantastic people. 💖

See the CONTRIBUTING.md guide to get involved.

BOTLANNER 💻 🔧

License

Licensed under MIT

---

We are hiring 🤝 Join us! 🇿🇦

https://www.capitecbank.co.za/about-us/careers