Notes on document

Please note, this document is in an early draft form. It’s primary purpose is to discover how we will define APIs, rather than discover the detail of a specific API method. In other words, now is not the time to ask “Why doesn’t it support xyz?”, however, it is a good time to ask “If we were to add xyz, where would it live?”

API Design Principles

Our general principles are as follows:

Following existing HTML5 API and JavaScript language standards
Rather than versioning the API, we will use the standard web-approach of feature discovery / detection (e.g. to determine if a container supports an API, check for the existence of the API methods)
When extending pre-existing APIs we will use a vendor prefix (TBD, perhaps -ssf-)
How an API is made available to a consumer is out of scope of this specification. It might be provided by the container runtime, or implemented by a polyfill, or may not exist at all.

SSF Notification API

The Notifications API is used to configure and display desktop notifications to the user. It is exposed as an extension to the HTML5 Notification API, providing additional functionality that is useful for financial desktop applications.

The exact visual style and the extent of the OS-level integration is container dependent and hence out-of-scope of this specification.

Constructor

Notification()

Creates a new instance of the Notification object.

Syntax

var myNotification = new Notification(title, options);

Note: the API should be exposed as a global namespace - working name "ssf" so:

var myNotification = new ssf.Notification(title, options);

Parameters

title

Defines a title for the notification, which will be shown at the top of the notification window when it is fired.

options (optional)

An options object containing any custom settings that you want to apply to the notification. These options can container the standard HTML5 notification API options

```
dir …
```
```
lang ..
```

In addition, the following ‘extension’ options are supported:

NOTE: These properties are currently illustrative!

-ssf-blink - causes the notification to blink
-ssf-blink-color - the color used for the blinking effect
ssf-blink-interval
-ssf-monitor-id - the id for the monitor that this notification is displayed on
ssf-target (targetId)

Need way to query available targets...

Container Implementation Details

Browser

This API is an extension of the HTML5 Notification API, therefore the standard features will be supported within a browser (depending on version).

NOTE: That the browser API requires the use of Notification.requestPermission

Electron

The Electron container supports HTML5 notifications, displaying them as OS-level notifications (e.g. notification centre on Mac). The container does not support notifications on Windows <8, or have direct support for the extension properties. Note: Electron is considering Windows 7 support (see: https://github.com/electron/electron/issues/8384). Everyone should put a thumbs up there.

The (currently fictional) electron-ssf-notification package provides a polyfill giving electron full support for the Symphony Notification API, including Windows 7.

OpenFin

Support of the Symphony Notification API can be achieved in OpenFin today via an extension package (polyfill).

Future versions of the OpenFin API will provide full native support for the Symphony Notification API.

Discussion points:

(From Nick) we have vendor prefixes in the web world, but these exist to handle the problem of competing implementations - which we don’t necessarily have. Plus, the success of the prefixing scheme in the web world is debatable and our mechanics are a bit different - since containers target specific chrome versions and don’t role versions forward automatically.
- (Colin) Prefixing is still widely used, without issues, see the examples on this page: https://developer.mozilla.org/en/docs/Web/API/Navigator/getUserMedia
(From Nick) Should our API be prefixed? E.g. new ssf.Notification. If the API is not prefixed - the only way to handle contention with browser globals like Notification would be via prototype decoration. The development community has largely rejected this approach as an anti-pattern.
- (Colin) I'd like to debate this one further, in order to handle contention you simply have to replace one global function with another, it's the standard polyfill approach. As an example, here is an electron Notification shim that allows the notification API to be used from the main process: http://bit.ly/2lW9RWW (apologies for the bitly link, some stupid Confluence plugin was mangling my github link!)