Customize notifications

If you need more flexibility than the basic notification options provide, you can define custom templates.

Custom templates enable you to customize more aspects of the visual format of notifications than the base notification options. The range of possible customizations provides considerable flexibility in formatting, while staying within the constraints of the purpose and form factor of notifications.

With a custom template, you can customize the following aspects of a notification card:

• Arrangement of sections
• Layout of body content

To define a custom template, you must use the TemplateCustom interface, rather than the TemplateMarkdown or TemplateList interfaces. In the NotificationOptions object that you pass to the create() function, you must include a templateOptions object that defines the template, and a templateData object that contains the data to populate the template.

A templateOptions object contains the following properties:

• buttons.align: Sets the alignment of the buttons in the button area.
• indicator.align: Sets the position of the indicator area.
• indicator.color: Sets the color of the indicator area.
• body: Defines one or more compositions (layouts) for the body area.

Arrangement of sections

You can change the alignment of the buttons (left vs. right) and the position and color of the indicator area:

The buttons.align property can be set to "left", "center", or "right"; the default value is "right".

The indicator.align property can be set to "left", "center", or "right"; the default value is "center". For "left" and "right", the indicator text is rotated correspondingly.

The header color can be set both in a template and when creating a notification instance. The color defined on a notification instance overrides the template color.

Customize the body section

The Notification Center supports a variety of styleable components (or “fragments”) within the body section.

You can arrange and style the following types of fragments:

• Container: ContainerTemplateFragment This type has no visible parts. It serves to group other fragments.
• Text: TextTemplateFragment
• List: ListTemplateFragment
• Image: ImageTemplateFragment

You can apply styles to template fragments using React inline style properties, defined in the style property of the fragment. Remember that React style properties use “camelCase” names, such as backgroundColor rather than “kebab-case” names, such as background-color, as in plain CSS.

📘

Do not use position:fixed

The position:fixed CSS property value is not allowed, to prevent elements from appearing outside their notification card; the create() function throws an error if it is used.

Data mapping

A fragment of a custom template can define data to be provided by each notification instance. For example, an image fragment could require a URL for an image file to be provided for each notification instance, so that the same template displays different pictures in different notification cards.

To enable mapping of data from notification instances to notification templates, each fragment type has a dataKey property. The value of this property is, in turn, used as the key of a key-value pair in the notification’s templateData property. For example, if an image fragment contains dataKey: 'imageUrl', then a notification using a template containing that fragment should define a value for imageUrl in the templateData property.

A fragment can also have an optional Boolean property. If it is true, and a value matching the dataKey is not present in a notification instance, then the fragment is simply not displayed. If optional is false or not defined, then missing data in a notification instance results in an error in the create() function.

The Notification Center library validates that the data provided in the notification instance is of the correct type. For example, if you pass list data for a text fragment, you get an error in the create() function.

Manage API versions

In future versions of the Notification Center API, OpenFin may introduce new fragment types as we identify new customer needs. However, this raises the possibility that an application might use a template with a fragment type from a newer API version, but run in an OpenFin environment where an older API version is installed.

To handle such a situation, you can define multiple compositions for a template, with a minimum version specified for each one. A layout with a recent minimum version can use all available fragment types; a “fallback” layout enables users whose environments are not current to still experience the notification with a more limited layout, following the principle of graceful degradation.

You can define a fallbackText property for a template, with a message to display if the environment version does not support any layout that you have defined.

You can discover the API version of the template library via the VERSION constant, which is a version string in semver format.

Apply a custom template to a notification

To apply a custom template to a notification you are creating, you pass the template as the templateOptions property of the NotificationOptions object, and pass data that is specific to the notification in the templateData property.

You can define a custom template for use within a single notification, or you can publish templates in a library for use by a range of applications.

import { StockWarningTemplate } from ‘MegaCorp-OpenFin-Template-Library’;

const megaCorpWarningNotification = {
// standard notification options go here
  template: ‘custom’,
  templateOptions: StockWarningTemplate,
  templateData: {
    ticker: ‘AAPL’,
    price: ‘$149.26’,
    change: ‘-0.64 (0.43%)’
  }
}

Await create(megaCorpWarningNotification);