Platform Developer Guide

If you are a Platform owner who wants to include OpenFin's web capabilities in your platform, there are a few steps required. This section will guide you through the process of setting up an environment. Please note, none of these steps are necessary for content developers (See the content developer guide).

First Steps

Ensure that @openfin/core-web is installed by running the following command:

npm i @openfin/core-web -S

Host the @openfin/core-web Shared Worker

An @openfin/core-web/shared-worker entry point is included in this package's distribution. This is a non-customizable, standalone piece of javascript that must be hosted on your server for @openfin/core-web to function.

This file has already been bundled, which means you just need to host it on a web server on a known URL.

Build a Web Broker

An HTML page, loaded as a hidden iframe by clients, must be hosted in the same origin as the @openfin/shared-worker. This iframe acts as a gatekeeper to the shared-worker and therefore must be hosted on the same domain.

In order to build a Web Broker, the following requirements must be met:

  1. You must host the @openfin/core-web/shared-worker bundle on a domain (for example https://www.example.com/mysharedworker.js).

  2. You must host a web broker page on that same domain (for example, https://www.example.com/web-broker).

  3. That page must call init from @openfin/core-web/iframe-broker with the URL of the shared worker hosted in step 1.

    // Runs on https://www.example.com/web-broker
    import {init} from '@openfin/core-web/iframe-broker;

    const sharedWorkerUrl = 'https://www.example.com/mysharedworker.js';

    await init({sharedWorkerUrl})

Here is a basic example of hosting a Web Broker:

Example: Set up a Basic Web Broker

First, host @openfin/core-web/shared-worker at /openfin-shared-worker.js

File: iframe-broker.html

<html>
    <body>
        <script src="iframe-broker.js"></script>
    </body>
</html>

File: iframe-broker.js

import { init } from '@openfin/core-web/iframe-broker';

init({
    sharedWorkerUrl: `${location.origin}/openfin-shared-worker.js`
});

Reject Connections

As an owner of an Iframe Broker, you should first rely on existing web security tools such as the frame-ancestors CSP rule to prevent content from connecting to you which you don't expect.

@openfin/core-web exposes a rejectConnections utility if you wish to implement custom rejection logic. If neither init or rejectConnection is invoked, an embedding client may hang indefinitely.

Example: Reject a Cross Origin Connection using @openfin/core-web/iframe-broker

import { init, rejectConnections } from '@openfin/core-web/iframe-broker';

// If the origins do not match.
if (new URL(document.referrer).origin !== location.origin) {
    rejectConnections({
        reason: 'Connections from this domain are not supported' // Reason allows an error to be returned to the connecting client.
    });
} else {
    init({
        sharedWorkerUrl: `${location.origin}/openfin-shared-worker.js`
    });
}

Experimental: Enable Cross Tab Support

By default, @openfin/core-web disables the sharing of connections across browser Tabs. However, this feature may be enabled by specifying the following flag in an IFrame Broker:

Example: Enable Cross Tab Support

init({
    sharedWorkerUrl: `${location.origin}/openfin-shared-worker.js`,
    experimental: {
        crossTab: 'same-site'
    }
});

Example: Enable logLevel for Debugging

@openfin/core-web features configurable logging using the logLevel connection option. It accepts the following values: 'debug', 'info', 'warn', 'error', 'none'. By default it is set to 'error'. Change the level to see more information in the console:

init({
    sharedWorkerUrl: `${location.origin}/openfin-shared-worker.js`,
    logLevel: 'debug'
});

const fin = await connect({
    connectionInheritance: 'enabled',
    options: { brokerUrl },
    platform: { layoutSnapshot },
    logLevel: 'debug'
});

Create Layouts

Layouts in the web are very similar to the desktop OpenFin environment. They consist of a layout configuration that describes the rows/columns/view components. The major difference is that the layout key is not supported. Instead, we expose the layoutSnapshot key to plug into the multiple-layout architecture. See the Multi-Layout guide for more information on how to set it up.

Note that you can achieve a single layout by having only 1 key in your layoutSnapshot:

const layoutSnapshot = {
    layouts: {
        layout: { ... }
    }
}

The JSON structure of the underlying layout options is interchangeable, though not identical, between Desktop and Web. Web Layout Snapshots have an optional web property within the view componentState options which stores web specific properties. This web property is ignored on desktop.

Layout Settings

Layouts in the web support the following LayoutOptions.settings:

  • reorderEnabled (Default value true): If true, users can re-arrange the layout by dragging items by their tabs to the desired location. Note, unlike in an OpenFin environment the dragging of items is limited to the current window.
  • hasHeaders (Default value true): Turns tab headers on or off. If false, the layout will be displayed with splitters only.
  • preventSplitterResize (Default value false): When true the splitters will not be draggable and the layout will not resize.
  • showMaximiseIcon (Default value false): Enables maximise button for stacks. The button maximises the current tab to fill the entire layout container.