AboutSupport

Customize Browser features

Suggest Edits

In Workspace 6.0 and 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.

In Workspace 9.1 and later, we've added the ability to remove the icon from view tab hats. This is useful if your workspaces include many tabs, or if your icon does not provide useful information about view content.

📘

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.

Here's what you can customize:

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 the menu customization 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.

  • 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

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.

Views

Starting in Workspace 10, 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.

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 9.1 and 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: {
      // 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
            // this is the only button you cannot customize
            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
});

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.

Updated 4 months ago