🚧

Requirements

• OpenFin CLI installed
• OpenFin Runtime 15.80.49.30+
• Windows Operating System | Mac not fully supported and may result in unexpected behavior

Window Customization

Windows created using the OpenFin Platforms act as a host (or container) for Views. If your content is rendered in Views, your window can be used to display UI controllers, and acts as a “frame” on top of which views are drawn.

Standard OpenFin Window

OpenFin Platforms comes pre-packaged with OpenFin’s Standard Window, which has standard 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.

Standard Window Customization

You can easily apply your own stylesheet to the standard window by specifying the stylesheetUrl property within defaultWindowOptions in your manifest (path/url must be absolute, not relative):

{
    "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 simply inspect the window using Chrome Developer Tools.

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 (url must be absolute, not relative).

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

// Layout.init must be called in the custom window to initialize the Layout and 
// load the views.  Call init on DOMContentLoaded or after the window is setup 
// and the target div element has been created
window.addEventListener('DOMContentLoaded', () => {
    fin.Platform.Layout.init({containerId: 'id-of-div'});
});

📘

defaultWindowOptions.stylesheetUrl and Custom Window

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

Using Keyboard Commands

OpenFin defines and implements a set of optional commands and behaviors specific to Platforms. You can configure keyboard shortcuts for the commands in the commands property of the platform object in your manifest. For details about the properties of command items, see the hotkeys option on Window.

{
    "platform": {
        "uuid": "example_platform",
        "defaultWindowOptions": {
            ...
        },
        "commands": [
            {
                "command": "stack.nextTab",
                "keys": "Ctrl+T"
            }
        ]
    },
    "snapshot": {
        ...
    }
}

Currently available commands

Some of the commands are also enabled by default. The following table shows the list of commands enabled by default and their hotkeys:

Keyboard command example

{
    "command": "view.detach",
    "keys": "Ctrl+D"
}

/*
To disable a command you can simply omit its 'keys' property
*/

{
    "command": "stack.zoomIn"
}

/*
You can disable all default commands using the 'disableDefaultCommands' 
property on your 'platform' object. Once you do that, you can enable 
only the ones you need one-by-one:
*/

{
    "platform": {
        ...,
        "disableDefaultCommands": true,
        "commands": [
            {
                "command": "stack.nextTab",
                "keys": "Ctrl+T"
            }
        ]
    }
    ...
}

Layout CSS Classes

When using a custom CSS file to modify the layout's appearance, one can extend or overwrite the internal CSS classes used by the layout to achieve a customized layout look and feel.

The following is a quick rundown of the main classes used by the Layout components:

• .lm_root - The top-level container of all other containers
• .lm_row - Represents a row of layout containers
• .lm_column - Represents a column of layout containers
• .lm_stack - Represents a pile of tabs stacked on top of each other
  • .lm_header - Contains lm_tabs lm_controls lm_tabdropdown_list
    • .lm_tabs - Contains all tabs in the current stack
      • .lm_tab - Contains the tab cap title and buttons
    • .lm_controls - Currently unused
    • .lm_tabdropdown_list - Contains all dropdown tabs in the current stack
      • .lm_tab - Contains the tab cap title and buttons
  • .lm_items - Contains all item containers in the stack
    • .lm_item_container - A placeholder div on top of which views are drawn. Will show an error message if a view fails to render

Customizing Platform Behavior

The Platform Provider is the communication hub that coordinates between all windows in a Platform. This Provider runs in a hidden window. By providing a custom Provider, users can overwrite or extend default Platform behavior.

Provide custom HTML for the Provider window

Because the Provider runs in a normal (hidden) OpenFin window, it needs an HTML document. To provide your own document, add a providerUrl property to your Platform's manifest:

// app.json
{
    "platform": {
        "uuid": "my-uuid",
        ...,
        "providerUrl": "https://my.server.com/platform-provider.html"
    },
    "snapshot": {
        ...
    }
}
```

Overriding default behavior in user-created HTML

The user-created HTML document must call fin.Platform.init to initialize the platform and open the manifest-defined snapshot.

Minimal custom Provider HTML

<html>
    <head>
        <script>
            fin.Platform.init();
        </script>
    </head>
    <body></body>
</html>

fin.Platform.init takes an options argument which may contain an overrideCallback property. The class that implements default Platform behavior is provided as an argument to this callback, and OpenFin uses the callback's return value to handle Platform functionality.

Using overrideCallback allows you to extend or replace default functionality in order to customize Platform behavior. To implement your own handlers for Platform behavior, extend the provided class and override any methods you'd like to alter.

Example: Overriding default getSnapshot behavior

const saveSnapshotToServer = async (snapshot) => {
    // async code here.
    // Send a snapshot to the server, store it locally somewhere, etc.
}

const overrideCallback = (Provider) => {
    // Extend default behavior
    class MyOverride extends Provider {
        async getSnapshot() {
            // Call super to access vanilla platform behavior
            const snapshot = await super.getSnapshot();
            // Perform any additional logic needed
            const modifiedSnapshot = { ...snapshot, answer: 42 }
            await saveSnapshotToServer(modifiedSnapshot);
            return modifiedSnapshot;
        }
    }
    // Return instance with methods to be consumed by Platform
    return new MyOverride();
};
fin.Platform.init({ overrideCallback });

You can perform any custom initialization before calling fin.Platform.init

const overrideCallback = async (Provider) => {
    // Do async stuff here
    const userInfo = await loginUser();

    // Extend default behavior
    class MyOverride extends Provider {
        async getSnapshot() {
            const snapshot = await super.getSnapshot();
            return { ...snapshot, userInfo };
        }
    }
    // Return instance with methods to be consumed by Platform
    return new MyOverride();
};
fin.Platform.init({ overrideCallback });