@interopio/iframes-api

Overview

The @interopio/iframes-api library provides a convenient API for starting applications in iframes.

Installation

To install the library, execute the following command:

npm install @interopio/iframes-api

Usage

The following examples demonstrate basic initialization of the @interopio/iframes-api library in io.Connect Browser projects.

io.Connect Browser

Initializing the @interopio/iframes-api library in the Main app of an io.Connect Browser project:

import IOBrowserPlatform from "@interopio/browser-platform";
import IOIFrames from "@interopio/iframes-api";

const config = {
    licenseKey: "my-license-key",
    browser: {
        libraries: [IOIFrames],
    }
};

const { io } = await IOBrowserPlatform(config);

// Now you can access the IFrames API via `io.iframes`.

Initializing the @interopio/iframes-api library in a Browser Client app of an io.Connect Browser project:

import IOBrowser from "@interopio/browser";
import IOIFrames from "@interopio/iframes-api";

const config = {
    libraries: [IOIFrames],
};

const io = await IOBrowser(config);

// Now you can access the IFrames API via `io.iframes`.

Using the IFrames API

// STEP 1 => create a map to store iframe containers by ID
const iframeContainers = {};

// STEP 2 => register listener for close requests
// onCloseRequested can only listen for iframe instances that are inside the app that registers the listener
const unsubscribe = io.iframes.onCloseRequested(async ({ id }) => {
    
    // remove the iframe container
    iframeContainers[id]?.remove();
    delete iframeContainers[id];
    
    // confirm to the platform that local cleanup is done, so it can remove the iframe and clean up its state
    await io.iframes.confirmFrameClosed(id);
});

// STEP 3 => start the app
const start = async () => {
    
    // create a container where the iframe will be visualized
    const createIFrameContainer = () => {
        const container = document.createElement("div");
        
        container.style.width = "400px";
        container.style.height = "300px";
        container.style.boxSizing = "border-box";
        container.style.border = "1px solid orange";

        container.innerText = "Loading ...";
    
        document.body.appendChild(container);
    
        return container;
    }

    const iframeContainer = createIFrameContainer();
    
    // start the app (the returned iframe is automatically attached to document.body)
    const { id, iframe } = await io.iframes.openApp({ appName: "simple", context: { ticker: "TMDX" }});

    // store the container so it can be removed when a close request is received
    iframeContainers[id] = iframeContainer;
    
    // position the iframe inside the container
    const positionIFrame = (iframe) => {
        const { top, left, width, height } = iframeContainer.getBoundingClientRect();
    	
        iframe.style.top = `${top}px`;
        iframe.style.left = `${left}px`;
        iframe.style.width = `${width}px`;
        iframe.style.height = `${height}px`;
    };

    iframeContainer.innerText = "";
    
    positionIFrame(iframe);

    
    return { windowId: id, iframe };
};

const { windowId, iframe } = await start();

// STEP 4 => close the app
await io.windows.findById(windowId).close();