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 tofalse
in thedefaultWindowOptions
. Theenabled
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 thecolor
property is absent, the border color will be set to the default Chrome theme. If thecolor
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.'");
});
Updated 8 months ago