Customize Browser features

In Workspace v6 or later, you can customize the behavior of Windows in the OpenFin Browser. In addition to providing custom themes for look and feel, you can now provide granular control over window behavior.

📘
Note
This article explains which window elements you can customize. To customize the entire Browser, you work with the Browser SDK.

Refer to Parts of windows in Browser for an explanation of OpenFin window terminology.

Features you can customize

You can customize the entire window and its elements, the page or pages within a window and their elements, and the toolbar and its elements and options.

In Workspace v18.0 or later, you can change the window title so that the title of the selected view or page is displayed. See Display different Browser Window titles.

You can also customize the following items:

Browser

Main Browser menu
- Add or remove options
- Change order of options
- Edit the label of each option

For an example of how to customize these items, see How To Customize Browser Menus in the workspace-starter GitHub repository.

Toolbar control buttons
- Add, disable, or remove buttons
- Change the order of options
- Change the icon or label associated with each button
- Allow the user to hide or show tabs

Buttons can be completely custom, and clicking them can invoke a callback you define. In Workspace v16.1 or later, you can customize the icon that's displayed when pages are locked or unlocked, or when tabs are shown or hidden. See the API reference for LockUnlockPageConfig and ShowHideTabsConfig.

Color linking control
- Add or remove color channels
- Change the order of color channels
- Change colors of channels
- Change default colors
- Edit the tooltip text for each color channel

Workspace v17.0 or later includes a download shelf UI that displays at the bottom of a Browser window. You configure the download shelf for either Views or Windows, but it is displayed in the Window, not the View. It's enabled by default for Views, but you can disable it. For a detailed explanation, see the download shelf article for Container.

An optional downloadShelf.enabled property of the BrowserCreateWindowRequest and BrowserCreateViewRequest objects lets you configure the download shelf for Views or for an entire Browser Window. BrowserCreateWindowRequest.downloadShelf supports options to customize the border of the shelf. See the API reference for DownloadShelfOptions.

Windows

Specify icon displayed in the upper-left corner (default OpenFin icon)
Control buttons in the upper-right corner (maximize, minimize, restore, close)
- Change icon or tooltip
- Disable any button
- Add custom button, including icon, tooltip, action, and disabled status
- Remove any button, or change the order of buttons
Specify default set of pages to display in a new window
Disable multiple pages, so that only a single page is available in the window
Specify title that appears if only a single page is displayed
Context menu
- Add or remove menu options
- Change order of options
- Edit label of each option
(new in Workspace 9.1) Whether icons are displayed on view tab hats. See Define initial customizations for how to do this.

Pages

See defaultPageOptions:

Default URL for new pages. You must specify this value to allow users to add new pages See the workspacePlatform object. The new page should provide a view that allows users to select appropriate content.
Page tabs:
- Change order
- Default URL for new tabs. As with new pages, you must specify this value to allow users to add new tabs to pages.
Page-tab close control (that is, the "x" icon that closes a page)
- Hide (default value: Show)
- Disable (default value: Enable)
Context menu (for pages or views)
- Add or remove menu options
- Change the order of options
- Change the label of each option
Whether a fixed panel is part of the Page. For details, see Add fixed panels to Browser Page.

In Workspace v13.1 or later, you can add custom metadata to the Page object. An optional customData property lets you specify any serializable data type you require, such as version or timestamp. This metadata can help you make sure your users are working with the appropriate version of the page, for example, or check when they last worked with it. See Define initial customizations for an example, and see the Page object in the API reference.

In Workspace v19.0 or later, you can customize the default Page with an override. See Create a custom default Page.

In Workspace v19.1 or later, you can override the Page close behavior with your own custom code. See Add custom code on Page close.

Views

In Workspace v10 or later, the View context menu includes an option to print the view. You can also add options to navigate Forward or Back, but you must explicitly enable them. To do so, add the following to your View manifest:

"contextMenuOptions": {
  "enabled": true,
  "template": [
    "back",
    "forward"
  ]
  }

See also View manifest options and for a complete listing View options.

To add the Back or Forward option to the View tab context menu, however, you work with platform overrides. For an example, see the API reference for WorkspacePlatformOverrideCallback.

When you allow users to add a new Page, or a new View within a Page, you should also specify a customized default View that presents appropriate content for users to select. See the example customization on this page for how to specify and call a custom View.

In Workspace v17.0 or later, you can also add the standard web browser controls to navigate forward or back in a View, or reload the active View. The BrowserWorkspacePlatformWindowOptions object includes a navigationButtons property that lets you enable navigation buttons or disable hotkeys for these buttons if you choose. You specify which navigation buttons to enable by adding the browserNavigationButtons property to the BrowserWorkspacePlatformViewOptions object. You can add any or all of the available buttons. See the API reference for View options, and for an example, the API reference for Window options. Make sure to call workspacePlatform.getViewSnapshot(view.identity) to retrieve the options you've set. A call to view.GetOptions() does not have access to the Workspace Platform you set the options on.

Examples

Most of these options are provided as part of the workspacePlatform property of the BrowserCreateWindowRequest interface.

To customize menu options, you define overrides as part of a BrowserOverrideCallback for your Workspace Platform.

The API reference documentation provides an example for the window context menu, openGlobalContextMenu. You can write similar overrides for the page context menu, openPageTabContextMenu, or for the view context menu, openViewTabContextMenu.

Define initial customizations

When you initialize a Workspace Platform by calling WorkspacePlatform.init(), you can define a BrowserInitConfig object that specifies Browser customizations. These include default options for windows, pages, and views, as well as overrides for interoperability and browser behavior.

In Workspace v9.1 or later, you can remove icons from view tab hats as part of defaultWindowOptions.

The following example is partial and is intended to show the range of possibilities for browser customization. For a complete example you can work from, see the Workspace-Starter example in GitHub.

import * as WorkspacePlatform from "@openfin/workspace-platform";

const customTheme: WorkspacePlatform.CustomThemes = 
[
  {
    label: "PLATFORM Custom Theme",
    palette: 
    {
      // Required color options
      brandPrimary: "#3bcca5",
      brandSecondary: "#1271b5",
      backgroundPrimary: "#b5b5b5" // hex, rgb/rgba, hsl/hsla only - no string colors: "red"
    }
  }
];

const browserInitConfig: WorkspacePlatform.BrowserInitConfig = 
{
  defaultWindowOptions: 
  {
    // hide icons on all view tab hats
    experimental: 
    {
      showFavicons: false
    },
    workspacePlatform: 
    {
      // The only required property. An array of pages to display in the Browser window.
      // Here we show only one Page with its required properties plus the customData property
      pages: 
      [
        {
          pageId: "ddfb783b-52cb-47eb-b25e-5205b28be97f",
          title: "Test Page",
          layout: 
          {
            content: 
            [
              {
                type: "stack",
                content: 
                [
                  {
                    type: "component",
                    componentName: "view",
                    componentState: 
                    {
                      url: "https://example.com"
                    }
                  }
                ]
              }
            ]
          }
          customData: 
          {
            // Example custom data
            test: Date.now().toString(),
            version: "1.0.0"
          }
        }
      ]
      // Required to allow users to add new pages
      // Specify a page where the user can select a View or an entire Page
      newPageUrl: "https://example.com/myPageAndViewSelector.html",
      // Required to allow users to add new Views
      // Specify a selector where the user can select a View only
      newTabUrl: "https://example.com/myViewSelector.html",
      toolbarOptions: 
      {
        buttons: 
        [
          {
            // disable the button that lets users show or hide tabs on a page
            type: WorkspacePlatform.BrowserButtonType.ShowHideTabs,
            disabled: true
          },
          {
            // customize other preconfigured buttons
            type: WorkspacePlatform.BrowserButtonType.SaveMenu,
            iconUrl: "https://example.com/custom_save_icon.svg",
            tooltip: "Save your work!"
          },
          {
            // you can add completely custom buttons
            type: WorkspacePlatform.BrowserButtonType.Custom,
            disabled: false, // optional, default value is false
            iconUrl: "https://example.com/custom_button_icon.svg",
            tooltip: "Here"s a fancy custom button",
            action: {
              customData: "test", // data required to process the custom action
              id: "CUSTOM_ACTION_ID"
            }
          }
        ]
      }
    }
  },
  defaultPageOptions: 
  {
    // If these properties are not defined, OpenFin defaults are used
    iconUrl: "https://example.com/icon.svg",
    unsavedIconUrl: "https://example.com/unsaved.svg",
    closeButton: 
    {
      // these are the default values; change to hide or disable the close button on a page
      // you specify other button customizations as part of PredefinedButtonConfig or CustomButtonConfig
      disabled: false,
      hidden: false
    }
  },
  defaultViewOptions: 
  {
    // Only name and target are required, but url is recommended to provide content for new tabs
    customData: "",
    url: "https://example.com/custom_content"
  }
};

const customActions = 
{
  CUSTOM_ACTION_ID: (payload: WorkspacePlatform.CustomActionPayload) => 
  {
    alert("This custom action works " + JSON.stringify(payload));
    return "someresponse";
  }
};

await WorkspacePlatform.init({
  theme: customTheme,
  browser: browserInitConfig
});

In Workspace v12.6 or later, fixed panels can be included in the defaultPageOptions property of BrowserInitConfig. For details, see Add fixed panels to Browser Page.

Retrieve customData from Page

You can write a platform provider override to retrieve the data you specified when you created your Page object:

import * as WorkspacePlatform from "@openfin/workspace-platform";
import { UpdateSavedPageRequest } from "@openfin/workspace";

// You provide the following methods in your override code
import { handlePageUpdate, isPageOld, getCurrentPageVersion } from "OVERRIDE_CODE_LIBRARY"; // your code

const overrideCallback: WorkspacePlatform.WorkspacePlatformOverrideCallback = async (
   WorkspacePlatformProvider
) => 
{  
  class Override extends WorkspacePlatformProvider {
     
      // override default behavior of applyWorkspace
      applyWorkspace = async (req: WorkspacePlatform.ApplyWorkspacePayload): Promise<void> => {
      
      // get and do something with the customData
      const pageVersion = getCurrentPageVersion();
      const pages = req.snapshot.windows[0].workspacePlatform.pages;
      const isVersionOld = isPageOld();
      
      if (isVersionOld) {
        // Platform can notify the user and send a new version
        // Platform can use (myVar as BrowserWindowModule).updatePage() to save
        handlePageUpdate();
      }
    };
  }
};

Change defaults for all Windows

You can set the defaultWindowOptions property of the BrowserInitConfig interface to customize the default values of customizable properties for all new Window objects. defaultWindowOptions takes a BrowserCreateWindowRequest object as its value.

📘Note

Features you can customize

Browser

Windows

Pages

Views

Examples

Define initial customizations

Retrieve customData from Page

Change defaults for all Windows

📘
Note