OpenFin windows

Windows created using the OpenFin Platform API act as a host (or container) for OpenFin Views. If your content is rendered in Views, your window can be used to display UI controllers, and acts as a "frame" within which views are drawn.

OpenFin standard window customization

The OpenFin Platform API includes OpenFin’s standard window, which has typical window controls (close, minimize, maximize) and some style customization.

As the name suggests, the standard window is used as the default window you get if you don’t specify the window’s URL upon creation.

494494

Example of OpenFin’s standard window

You can easily apply your own stylesheet to the standard window by specifying the stylesheetUrl property within defaultWindowOptions in your manifest. The path or URL must be absolute, not relative.

Example of setting stylesheetUrl:

{
    "platform": {
        "uuid": "example_platform",
        "defaultWindowOptions": {
            "stylesheetUrl": "full-url-to-css-stylesheet"
        }
    },
    "snapshot": {
        ...
    }
}

📘

Overriding standard frame CSS selectors

To get an idea of the selectors that are available for you to override, take a look at the Platform style examples or inspect the window using Chrome Developer Tools.

Modal windows

You can create windows that are modal relative to a parent window. This enables you to create the same effect as modal dialog boxes in native applications. To create a modal window, add modalParentIdentity to the window options when you create it. It's also important, for usability, to set autoShow to true; otherwise, it could be hidden but still blocking interaction with its parent window.

Example in JavaScript of creating a modal window:

let winOption = {
        name:'child',
        defaultWidth: 300,
        defaultHeight: 300,
        url: 'https://cdn.openfin.co/docs/javascript/stable/tutorial-Window.create.html',
        frame: true,
        autoShow: true,
        modalParentIdentity: {uuid: "OpenfinPOC", name: "OpenfinPOC"}
    };
fin.Window.create(winOption);

Complete window customization

You can also overwrite OpenFin's standard window and "bring your own window." To do so, specify the url property as a window option in your manifest. This HTML file must contain a div component where you want the layout to be rendered. Use this div as the containerId property when you call Layout.init to initialize the Layout in the window and load the views. A url can also be specified in windowOptions in a snapshot, or when launching a snapshot via other methods. The URL must be absolute, not relative.

Example of overriding the window with url:

{
    "platform": {
        "uuid": "example_platform",
        "defaultWindowOptions": {
            "url": "full-url-to-html-file"
        }
    },
    "snapshot": {
        ...
    }
}

The Layout.init() method must be called in the custom window to initialize the layout and load the views. Call init() on the DOMContentLoaded event or after the window is set up and the target <div> element has been created.

window.addEventListener('DOMContentLoaded', () => {
    fin.Platform.Layout.init({containerId: 'id-of-div'});
});

📘

defaultWindowOptions.stylesheetUrl and custom windows

Note that defaultWindowOptions.stylesheetUrl is supported only for overriding standard window styles. If you are providing a custom window, include your stylesheets in your custom HTML document.

Popup windows

OpenFin V26 introduces a new API to make creating and managing Popup windows easier for developers. Popup windows are independent windows which are not restricted to the bounds of the DOM of the calling window. This allows content to be displayed on top of views. Some use cases for popup windows are right-click context menus, dialog boxes, floating help windows, and tooltips.

Popup windows also close when the launching view or window closes.

Example in JavaScript of a simple popup window:

const result = await fin.me.showPopupWindow({
    url: 'https://app_popup_url_here',  // The URL of your app's popup window.
    x: 150,                             // The x location for the upper left corner of your popup window.
    y: 100,                             // The y location for the upper left corner of your popup window.
    height: 150,                        // The popup window height.
    width: 300                          // The popup window width.
});

Popup windows can be placed programmatically so that you can place the window in a logical location, such as near the button the user clicked to launch the popup window.

Example in JavaScript of programmatic placement of the popup window:

const parentWindow = await (fin.me as OpenFin.View).getCurrentWindow();
const { identity: modalParentIdentity } = parentWindow;
const parentBounds = await parentWindow.getBounds();
const result = await fin.me.showPopupWindow({
    url: location.href.replace('app', 'popup'),
    x: Math.floor(parentBounds.width / 8),  // Location and size of popup window derived from parent window bounds.
    y: Math.floor(parentBounds.height / 8) - PARENT_FRAME_OFFSET,
    height: Math.floor(parentBounds.height - parentBounds.height / 4),
    width: Math.floor(parentBounds.width - parentBounds.width / 4),
});

Popup windows can return one or many results. By default when showPopupWindow is called it will wait for the popup to be dismissed or call dispatchPopupResult. If an onPopupResult callback is passed to showPopupWindow, the popup can dispatch many results to the caller and showPopupWindow will wait for the popup window to be dismissed.

Example in JavaScript of creating a popup window that sends multiple results:

const { right, height } = event.target.getBoundingClientRect();
const result = await fin.me.showPopupWindow({
    initialOptions: {
        customData: await fin.me.interop.getContextGroups()
    },
    url: location.href.replace('app', 'popup'),
    x: right + 5,
    y: Math.round((height / 2) + 15),
    height: 30,
    width: 250,
    resultDispatchBehavior: 'none',
    onPopupResult: (result) => {
        renderPopupResult(result);
    }
});
renderPopupResult(result);

Just as normal windows can be modal, popup windows can be modal windows as well. Just add modalParentIdentity in the initialOptions of the popup window.

Example in JavaScript of another way to add modalParentIdentity to the initial window options:

const result = await fin.me.showPopupWindow({
    initialOptions: {
        modalParentIdentity
    },
    url: 'https://app_popup_url_here',  // The URL of your app's popup window.
    x: 150,                             // The x location for the upper left corner of your popup window.
    y: 100,                             // The y location for the upper left corner of your popup window.
    height: 150,                        // The popup window height.
    width: 300                          // The popup window width.
    blurBehavior: 'modal'
});

Window-closing behavior

When the user tries to close an app with unsaved changes, or navigate away from a form that hasn't been submitted, you can launch a warn-before-close dialog window. A warn-before-close dialog window is completely controlled by you as the platform provider and is exposed as an override that can be customized.

To intercept the close of a window or view:

  • Set "enableBeforeUnload": true under the Platform options in the app manifest.
  • Override the getUserDecisionForBeforeUnload function as in the example below.

Example in JavaScript of how to use a warn-before-close dialog:

const overrideCallback = async (PlatformProvider) => {
    class MyOverride extends PlatformProvider {
 
        // By overriding this function we can intercept the close action
        // of any Window or View and show our own custom dialog.
        async getUserDecisionForBeforeUnload(payload) {
 
            // We gather all relevant information from the payload:
            // Which views are preventing the unload and which aren't.
            // Also, if this a Window or View close.
            const { windowClose, 
                    viewsPreventingUnload, 
                    viewsNotPreventingUnload, 
                    windowId, 
                    closeType } = payload;
 
            // Launch a dialog that displays the relevant information to the user.
            const continueWithClose = await launchDialog(viewsPreventingUnload, windowId, closeType);
 
            if (continueWithClose) {
 
                // If the user decides to close the view, we send back an array of Views to close,
                // and whether the Window should close or not close.
                return { windowShouldClose: windowClose,
                         viewsToClose: [...viewsNotPreventingUnload, ...viewsPreventingUnload] };
            } else {
 
                // If the user cancels the close, we send an empty array of Views to close,
                // and indicate that the Window should not close.
                return { windowShouldClose: false, viewsToClose: [] };
            }
        }
    }
    return new MyOverride();
};

See also


Did this page help you?