Skip to main content

Customize Browser features

In Here™ Core UI Components v6 or later, you can customize the behavior of windows in the Browser component. In addition to providing custom themes for look and feel, you can now provide granular control over window behavior.

Refer to Parts of windows in Browser for an explanation of Here™ Core UI 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 Here™ Core UI Components 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:

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 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 Here™ Core UI Components 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

Here™ Core UI Components versions 17.0 or later include 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 is the 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 Here™ Core UI Components 9.1) Whether icons are displayed on view tab hats.

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 Here™ Core UI Components 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 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 Here™ Core UI Components v19.0 or later, you can customize the default Page with an override. See Create a custom default Page.

Views​

In Here™ Core UI Components 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 of View options.

However, to add the Back or Forward option to the View tab context menu, 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 Here™ Core UI Components v17.0 or later, you can also add can 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 WorkspacePlatform 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 Here Core UI 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 Here Core UI 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 Here™ Core UI Components v9.1 or later, you can remove icons from view tab headers 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
});

Retrieve customData from a Page​

You can write a platform provider override to retrieve the data you specified when you created a 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.

Table of Contents