Webhandle Event Notification Panel

A panel to display notifications to users on the screen. It's got the basic options you'd need including message types, auto-disappearing mesages, user based removal of messages, progress of ongoing processes, and user cancelation of ongoing processes.

Install

1npm install @webhandle/event-notification-panel

Usage

As part of an application

HTML placement

1<div id="event-notifications"></div>

To include the styles

1@import "../node_modules/@webhandle/event-notification-panel/less/components.less";

or

1@import "../node_modules/@webhandle/event-notification-panel/public/css/event-notification-panel.css";

In the client side js bundle:

1import {setup} from '@webhandle/event-notification-panel'
2// or
3// const setup = require('@webhandle/event-notification-panel').setup
4let panel = setup({
5	notificationHolder: '#event-notifications' /* Optional. The selector of the element to which the
6												  panel should be added. */
7})
8panel.addNotification({
9	model: {
10		status: 'success',
11		headline: 'message 1'
12	}
13})

Options

Panel Options

You can pass options to EventNotificationPanel which modify how the underlying View component work. However, there are no creation options specific to the panel.

Options are available for the addNotification method.

1let eventView = panel.addNotification({
2	model: notification /* the data to notify */
3	, ttl: 2000 /* The time in milliseconds before the notification is automatically removed */
4	, closed: true /* Determines whether the notification details are initially shown. Default is true */
5})

Notification options

The notification itself has some required data elements and many optional. Ideally you'd use client-js/notification.mjs but that's not required.

1let eventView = panel.addNotification({
2	model: {
3		status: 'success' /* Required. Should be one of 'success', 'info', 'error', 'warning', 'waiting', or 'performing'.
4							 Values 'waiting' and 'performing' are special in that they indicate a notification which should
5							 NOT be automatically removed, even if a time to live (ttl) is specified. These types
6							 indicate either an event where the code isn't able to offer information on when it will 
7							 be complete (waiting), or an event where a progress bar should be shown to update the
8							 user about progress (performing). */
9		, headline: "Copy complete" 	/* Required. The main message to show the user */
10		, message: "Copied file /a/b/c"	/* Optional. A detailed message which the user may or may not see. */
11		, progressComplete: 0			/* Optional. An integer from 0 to 100 which indicates how much progress has been
12										   made on this task. Update this value to change how much progress is shown
13										   on the bar. The panel is told to update the html by triggering an event.*/
14		, cancelable: true				/* Optional. If true, the event will show a cancel button which will allow the
15										   user to cancel this task. */
16	}
17})

Events

Events are available from the EventNotificationView object returned by the addNotification method.

1let eventView = panel.addNotification({
2	model: {
3		status: 'performing'
4		, headline: "Copying file"
5		, cancelable: true
6	}
7})
8
9let emitter = eventView.notification

The notification object is a browser EventTarget extended with the on and emit methods familiar from Node's EventEmitter class.

To indcate that the panel should update based on changed information in the model:

1emitter.emit('modelUpdate')

There are lifecycle events that code can listner for. All of the events have the pattern:

1emitter.on('eventName', function(eventNotificationViewObject) {
2	// User's code
3})

Emitted Events

• initialize: The view's initialize method is being run
• nodeAdd: The view's root node is added to the DOM. This is an important internal event for calculating ttl.
• render: When the view is rendered
• expandMessage: The user has chosen to expand the notification to see the details
• cancel: The user has asked to cancel the operation
• startRemove: The panel has started visual effects to indicate that the event is being removed.
• remove: When the view's root element is being removed from the DOM. This does NOT delete the DOM fragment.

Usage as a dynamically loaded component

This can also be used just by itself without being built into an application. This is not my primary current use case, so I'm putting the documentation farther down so as not to crowd out the meat at the top, but it works perfectly.

On the server side

If you're using webhandle you can set everything up like:

1const webhandle = require('webhandle')
2import('@webhandle/event-notification-panel').then(mod => {
3	mod.default(webhandle)
4})

Otherwise what you'll need to do is make the content from the module in @webhandle/event-notification-panel/public available to the browser via the server. For this example that content is available at /@webhandle/event-notification-panel/resources

HTML placement

1<div id="event-notifications"></div>

Styles

1<link href="/@webhandle/event-notification-panel/resources/css/event-notification-panel.css" rel="stylesheet">

Client side js

1<script type="module">
2	import {setup} from '/@webhandle/event-notification-panel/resources/js/event-notification-panel.js'
3	let panel = setup()
4	panel.addNotification({
5		model: {
6			status: 'success',
7			headline: 'message 1'
8		}
9	})
10</script>