Skip to main content

Dock 2

info

Dock 3 represents a fundamental architectural shift from Dock 2 or Dock 1. Dock 3 introduces a per-platform architecture where each workspace platform owns its dedicated dock instance. Built to share the same core implementation as HERE Enterprise Browser, it delivers visual consistency while eliminating singleton limitations.

The Dock 2 component provides a floating toolbar, which offers standard actions by default, and, if configured, enables users to rearrange the actions and add favorites to it.

In HERE Core UI Components 9 and later versions, the Dock 2 component lets users launch other HERE Core UI components, or switch workspaces.

In HERE Core UI Components 13 and later versions, the Dock 2 configuration can be dynamically updated. For details, see Dynamic elements in Dock 2.

In version 21 and later, users can restore the last saved version of a workspace. You can create your own workflows that involve this option, using the restoreLastSavedWorkspace() method.

How Dock 2 works​

Much like Store or Home, you include Dock in your HERE Core UI implementation by registering a Dock provider. Unlike Store or Home, you must register a unique Dock provider for each HERE Core UI platform that you create. Each platform appears in a single Dock for your users to choose from.

The Dock UI renders the theme that you define for your HERE Core UI platform, just as Home, Store, and Notification Center do. For more information, see HERE Core UI themes with color-picking.

By default Dock contains buttons for Home, Store, and Notifications. It also includes a dropdown list with available workspaces and an option to restore the last saved version of the current workspace. These buttons are shown by default, but you can hide them.

If the user selects the Restore to Last Saved Changes option, a confirmation dialog appears, because more-recent changes are lost with this action.

You can also add custom buttons for custom actions or functionality. Starting in HERE Core UI Components v21.0 or later, you can configure custom buttons so that users can remove them if wanted: set the removeOption property in the contextMenu member of the DockButton object to true. By default, custom buttons are not removable. See the Workspace API reference for details.

In HERE Core UI Components v17.0 or later, dropdown lists can include arrays of lists, to support multiple menu levels. For more information and examples, see the Workspace API reference for DockProvider.

How to use Dock 2​

import * as Dock from "@openfin/workspace";

const dockProvider: DockProvider = 
{
  // This provider shows only the default HERE Core UI components
  title: "DOCK TITLE",
  id: "UNIQUE_DOCK_ID",
  // must be in raster image format. SVG format is not supported.
  icon: "EXAMPLE.COM/DOCK_ICON.png",
  buttons: [
        {
      tooltip: 'Sample Button 1',
      iconUrl: 'https://EXAMPLE.COM/BUTTON1_ICON.png',
      action: {
        id: 'sampleButton1',
      },
      contextMenu: {
        removeOption: true,
      },
    },
  ]
};

Dock.register(provider: dockProvider);
// you must explicitly call this function to display the Dock. Dock is hidden by default.
Dock.show();

Dynamic elements in Dock 2​

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 2 to be re-registered if any changes are made to the configuration.

How dynamic elements work​

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 use dynamic elements​


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