Skip to main content

Configure dynamic Dock

In Here™ Core UI Components v13 and later, users can rearrange elements in the Dock UI or add apps to their favorites, and their arrangements persist by default. If your platform makes any changes to the Dock configuration, Dock is dynamically updated with these changes. Earlier Here Core UI Components versions require Dock to be re-registered if any changes are made to the configuration.

How it works​

When you register a Dock provider, a DockProviderRegistration object is returned that includes a new updateDockProviderConfig method. You call this method to update Dock with any new configuration you provide. The DockProviderConfig and WorkspaceButtonsConfig interfaces support this functionality. For details, see the Dock API reference.

You can disable or limit user modification of their Dock in the following ways:

  • To allow users to rearrange their Dock but disable state persistence of their configurations, set the skipSavedDockProviderConfig property of the DockProvider object to true (default false).

  • To disable user configuration of Dock entirely, set the disableUserRearrangement property of the DockProvider object to true (default false).

  • To prevent users from removing custom buttons, omit the removeOption property from the button definition; by default, it is false, which prevents removal.

How to do it​


const dockProvider: DockProvider = {
  title: "MY DOCK TITLE",
  id: "MY_UNIQUE_DOCK_ID",
  icon: "https://EXAMPLE.COM/DOCK_ICON.png"

  // set one or the other of the following two properties, but not both
  
  // default value false; set to true to keep user rearrangement state from persisting
  skipSavedDockProviderConfig: true

  // default value false; set to true to completely disable user configuration
  disableUserRearrangement: true
};

const dockRegistration = Dock.register(dockProvider);

Dock.show();

// update Dock configuration for the provider
const newConfig: DockProviderConfig = {
  buttons: [{
    tooltip: 'Updated button',
    iconUrl: 'https://EXAMPLE.COM/BUTTON_ICON.png',
    action: {
      id: 'sampleButton1'
      },
      },
      contextMenu: {
        removeOption: false, // False by default, but shown for completeness
      },
  }]
};

await dockRegistration.updateDockProviderConfig(newConfig);

Dock configuration storage​

By default, any Dock configuration is saved in local storage. To save Dock configurations to your preferred storage location, you can write a WorkspacePlatformOverrideCallback to specify your preferred storage solution with overrides of the *DockProviderConfig methods of the WorkspacePlatformProvider interface.

Your override looks like:

import * as WorkspacePlatform from '@openfin/workspace-platform';
const overrideCallback: WorkspacePlatform.WorkspacePlatformOverrideCallback = async (
   WorkspacePlatformProvider
) => {
  class Override extends WorkspacePlatformProvider {
    getDockProviderConfig = async (id: string) => {
      // retrieve dock configuration by id from platform developer's custom storage.
    };
    saveDockProviderConfig = async (config: DockProviderConfigWithIdentity) => {
      // save dock configuration in platform developer's custom storage.
    };
  }
  return new Override();
};
await WorkspacePlatform.init({ overrideCallback });

Table of Contents