Add a jump list to a taskbar icon

The OpenFin API enables an OpenFin application to use the capability provided by Windows and Electron to define a jump list on the application’s icon in the system taskbar. A jump list is a menu that appears when the user right-clicks the taskbar icon, providing quick access to functions such as opening commonly-used files or other actions you choose to create.

For example, you could define jump list items that do the following:

• Customize the icon, title, or description of the application

• Launch the application in a specific state, such as maximized or in dark mode

• Launch into entry points such as most-recently or most-frequently used content

• Launch related tools

When you define a jump list for an application, Windows automatically adds a Pin to taskbar item to the menu. This option keeps the icon in the taskbar even when the application is not running.

To define a jump list, you call the setJumpList() method on the application object, and pass it an array of JumpListCategory objects. If the array is empty, the jump list is set to the system default.

Jump list categories

A JumpListCategory object consists of an optional name and an array of JumpListItem objects. If name is undefined, its items are placed in the standard ‘Tasks’ category at the bottom of the jump list. There can be only one unnamed category in an application’s jump list.

Jump list items

In a JumpListItem object, the type property can be set to either "task" or "separator". If it is "separator", any other properties for the item are ignored.

The other properties for a JumpListItem object let you define the menu item text (title), tooltip (description), link (deepLink), and icon (iconPath and iconIndex).

The deepLink property is a URL to invoke when the end-user selects the item. This must be a link to your application using the fins: custom protocol, including any URL parameters. It cannot be a local file path or an HTTP(S) URL. If you use parameters in the URL, your application code needs to be able to handle them appropriately. The RVM passes parameters that start with $$ in an array of key-value pairs. The RVM treats parameters with no prefix or only one dollar sign ($) as part of the base URL. Your application must handle these parameters appropriately. Refer to Deep linking for more details.

Troubleshooting tip: Watch out for stale links

Links in jump list items can become invalid if both of these conditions happen:

1. The end-user pins the application’s icon to the taskbar.

2. The application’s URL changes.

In such a case, the pinned icon’s jump list could contain links to the previous location, which could result in either a “not found” error or launching an “old” version of the application. If your application’s URL changes regularly, OpenFin recommends not using jump lists, to avoid this problem.