The download shelf

Web browser users like to see the files they've downloaded and to know the progress of their downloads that are in progress.
Web browsers, such as Google Chrome, do this by showing a download tray at the bottom of the browser window with the files listed in the tray.

Files that are downloading or downloaded appear in the download shelf UI at the bottom of the window.
The most recent downloads appear on the left side of the download shelf UI and are moved to the right as new downloads begin.
If a user wants more detail on their downloads, the download shelf UI contains a Show all button which can reveal a detailed display of downloaded and downloading files.

Starting in version 34 of the OpenFin Runtime, OpenFin provides a web-browser-like download experience in the download shelf.

The OpenFin download shelf gives a web browser-like file download experience to OpenFin apps and platforms.
In addition, the border of the download shelf can be set to a custom color and size.

How to programmatically use the download shelf

The download shelf is enabled by adding a setting to the defaultWindowOptions and/or defaultViewOptions.
When enabled, the OpenFin Runtime will show or hide the download shelf UI based on user actions.
Some actions have events your apps can respond to. Specifically, these events are:

• show-all-downloads which is raised by a Show all button click.

• download-shelf-visibility-changed which is raised when the download shelf UI is displayed or hidden, or when the download shelf UI border color or size have changed.

Download shelf settings

Add DownloadShelfOptions to defaultWindowOptions and/or defaultViewOptions. Adding DownloadShelfOptions to defaultWindowOptions will enable windows to invoke the download shelf UI.
Likewise, adding DownloadShelfOptions to defaultViewOptions will enable views to invoke the download shelf UI.

// The DownloadShelfOptions property manages the download shelf on OpenFin applications.
//   DownloadShelfOptions can be used in defaultWindowOptions and defaultViewOptions.

type DownloadShelfOptions = {
    enabled: boolean;   // Required. Implicitly defaults to false if no options provided.
    border: {           // Sets the options for the download shelf border.
        size?: number;  // Sets the number of pixels for the left, right, and bottom border of frameless windows, default 1. 
                        //   The top border is fixed to 1 pixel regardless of this setting.
        color?: string; // Sets the hex color code for the border. Defaults to the chrome theme if absent.
    }
}

The enabled property

When the enabled property is set to true, programs running in the window context or view context will show the download shelf UI at the bottom of the window when a file download begins.
When the enabled property is set to false, programs running in the window context or view context will not show the download shelf UI.
If you disable the download shelf for a window, that does not disable it for views contained in the window.
If you want to completely prevent the download shelf from appearing, you must disable it for both windows and views.

📘

Note

Downloads can occur regardless of whether the download shelf UI is enabled or not. The enabled property does not enable or disable download functionality.

Also, the download shelf UI will appear at the bottom of the window even if the enabled property is set to false in the defaultWindowOptions. The enabled property enables a window or a view to display the download shelf UI; it does not set where the download shelf UI will appear. The download shelf UI will always be attached to the bottom of the window, not to the bottom of a view.

The border property

The DownloadShelfOptions can customize the color of the download shelf and the size of the left, right, and bottom border. The top border is fixed at a size of 1 pixel.

Note that the border size and color settings only apply if the window is frameless.

The border property controls the download shelf border size and color. Within the border property are the optional properties size, and color.

• The size property controls the border size in pixels for the left, right, and bottom border.

• The color property controls the color of the border. If the color property is absent, the border color will be set to the default Chrome theme. If the color property is present, color must be set to an HTML hex color code.

Download shelf events

There are two events that the download tray raises: The show-all-downloads event and the download-shelf-visibility-changed event.

The show-all-downloads event

The show-all-downloads event is raised when the user clicks the Show all button on the download tray. This event can be used to display a full download page, such as the default Chromium download page (chrome://downloads) or a custom page written for your application.

In the following example, the chrome://downloads page appears when the user clicks on the Show all button.

const platform = await fin.Platform.getCurrentSync();

// Listen to the propagated event at the Platform level, so we only need one listener for a click from any window.
platform.on('window-show-all-downloads', () => {

  // Render the `chrome://downloads` window when a user clicks on the download shelf `Show All` button.
  platform.createWindow({
        name: 'show-download-window',
        layout: {
            content: [
                {
                    type: 'stack',
                    content: [
                        {
                            type: 'component',
                            componentName: 'view',
                            componentState: {
                                name: 'show-download-view',
                                url: 'chrome://downloads'
                            }
                        }
                    ]
                }
            ]
        }
    });
});

The download-shelf-visibility-changed event

The download-shelf-visibility-changed event is raised when the download shelf is revealed or hidden. It is also raised when the download shelf border color or size changes. This can be used to dynamically toggle the styling of the rest of the page should it conflict with the download shelf.

In the following example, when the download shelf visibility changes, the event is logged to the console.

// Get the platform.
let myPlatform = fin.Platform.getCurrentSync();

// When the download shelf visibility changes, log the event.
myPlatform.on('window-download-shelf-visibility-changed', e => {
    if (e.visible === true)
        console.log("Download shelf visibility changed to 'visible.'");
    else
        console.log("Download shelf visibility changed to 'not visible.'");
});