How to configure custom notifications

This guide describes how to trigger, dismiss, and remove notifications. Notifications can direct the attention of the author to something that happened.

What you need

You will need a Fonto Editor instance, which can be set up by following the Create a base editor guide.

1

Create a button to trigger a notification

Notifications can be triggered by calling the triggerNotification function.

In this step we will be adding a button to the toolbar using the Button component instead of FxOperationButton. If you'd like to trigger a notification from an operation consider introducing a custom action.

When using React, the useCallback hook is great for creating callbacks, such as one that triggers a notification. Pass the callback to Button's onClick prop to make sure the notification is triggered as soon as the button is clicked!

Using triggerNotification, useCallback and Button together we can update packages/editor-masthead/src/toolbars/ExampleToolbar.jsx to the following:

ExampleToolbar.jsx

JSX

import React, { useCallback } from 'react';
import { Button, MastheadToolbar, MastheadToolbarButtons } from 'fds/components';

import t from 'fontoxml-localization/src/t.js';
import triggerNotification from 'fontoxml-notifications/src/triggerNotification.js';

const ExampleToolbar = () => {
	const handleTriggerNotification = useCallback(() => {
		triggerNotification('Your notification', {
			message: 'Here is your notification.',
			icon: 'far fa-gem',
			colorName: 'icon-m-warning-color',
			dismissAfterMs: 10000
		});
	}, []);

	return (
		<MastheadToolbar>
			<MastheadToolbarButtons>
				<Button
					label={t('Trigger a notification')}
					onClick={handleTriggerNotification}
				/>
			</MastheadToolbarButtons>
		</MastheadToolbar>
	);
};

export default ExampleToolbar;

If you refresh your Editor you should now see the following toolbar button:

And when clicked, it triggers a notification like this:

2

Create a button to dismiss all notifications

Calling triggerNotification returns two functions with which your notification can be dismissed or removed again. The code responsible for triggering notifications is also responsible for clearing them, unless they time out automatically.

For example:

JavaScript

const { dismiss, remove } = triggerNotification('Your notification');

// Hide the notification from view
dismiss();

In this step we're adding the dismiss callbacks for our notifications into an array, so that a different button can call all of them to dismiss all notifications.

Because this is a simple example, using React's useState to store the dismissal callback. A new <Button /> can be used again to run all those callbacks when it is clicked:

ExampleToolbar.jsx

JSX

import React, { useState, useCallback } from 'react';

import { Button, MastheadToolbar, MastheadToolbarButtons } from 'fds/components';

import t from 'fontoxml-localization/src/t.js';
import triggerNotification from 'fontoxml-notifications/src/triggerNotification.js';

const ExampleToolbar = () => {
	const [dismissCallbacks, setDismissCallbacks] = useState([]);

	const handleTriggerNotification = useCallback(() => {
		const { dismiss } = triggerNotification('Your notification', {
			message: 'Here is your notification.',
			icon: 'far fa-gem',
			colorName: 'icon-m-warning-color',
			dismissAfterMs: 10000
		});

		setDismissCallbacks(dismissCallbacks => dismissCallbacks.concat([dismiss]));
	}, []);

	const handleDismissNotifications = useCallback(() => {
		dismissCallbacks.forEach(dismiss => dismiss());

		setDismissCallbacks([]);
	}, [dismissCallbacks]);

	return (
		<MastheadToolbar>
			<MastheadToolbarButtons>
				<Button
					label={t('Trigger a notification')}
					onClick={handleTriggerNotification}
				/>
				<Button
					label={t('Dismiss all notifications')}
					onClick={handleDismissNotifications}
				/>
			</MastheadToolbarButtons>
		</MastheadToolbar>
	);
};

export default ExampleToolbar;

Now click the Trigger a notification button and then click the Dismiss all notifications button.

Notifications when they are dismissed are moved into the Notification Center, at the bottom right of your screen. When this happens, the notification bell will get a blue highlight:

3

Create a button to remove all notifications

Removing a notification means removing it from view and removing it from the Notification Center itself.

Removing a notification is otherwise very similar to dismissing it programmatically; by calling the remove callback.

In this step we store remove callbacks in another array by using useState and then a new <Button /> can be used again to run all those callbacks when it is clicked:

ExampleToolbar.jsx

JSX

import React, { useState, useCallback } from 'react';

import { Button, MastheadToolbar, MastheadToolbarButtons } from 'fds/components';

import t from 'fontoxml-localization/src/t.js';
import triggerNotification from 'fontoxml-notifications/src/triggerNotification.js';

const ExampleToolbar = () => {
	const [removeCallbacks, setRemoveCallbacks] = useState([]);
	const [dismissCallbacks, setDismissCallbacks] = useState([]);

	const handleTriggerNotification = useCallback(() => {
		const { dismiss, remove } = triggerNotification('Your notification', {
			message: 'Here is your notification.',
			icon: 'far fa-gem',
			colorName: 'icon-m-warning-color',
			dismissAfterMs: 10000
		});

		setRemoveCallbacks(removeCallbacks => removeCallbacks.concat([remove]));
		setDismissCallbacks(dismissCallbacks => dismissCallbacks.concat([dismiss]));
	}, []);

	const handleDismissNotifications = useCallback(() => {
		dismissCallbacks.forEach(dismiss => dismiss());

		setDismissCallbacks([]);
	}, [dismissCallbacks]);

	const handleRemoveNotifications = useCallback(() => {
		removeCallbacks.forEach(remove => remove());

		setRemoveCallbacks([]);
		setDismissCallbacks([]);
	}, [removeCallbacks]);

	return (
		<MastheadToolbar>
			<MastheadToolbarButtons>
				<Button
					label={t('Trigger a notification')}
					onClick={handleTriggerNotification}
				/>
				<Button
					label={t('Dismiss all notifications')}
					onClick={handleDismissNotifications}
				/>
				<Button
					label={t('Remove all notifications')}
					onClick={handleRemoveNotifications}
				/>
			</MastheadToolbarButtons>
		</MastheadToolbar>
	);
};

export default ExampleToolbar;

Now click the Trigger a notification button and then click the Remove all notifications button.

After removal, the notifications will be removed from view and the Notification Center. If you click the notification bell, you will see there is no notification.

As a result, you will have three buttons to trigger, dismiss and remove notifications.