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.
Updated about 2 months ago