This module implements a way to display notifications to logged-in users that can be triggered from either the server- or browser-side using
apos.notify. These notifications can be customized for type, e.g.
success, and can also emit bus events that can be used to trigger actions. The module itself has two options for controlling new notice polling frequency.
|Interval in milliseconds between MongoDB queries
|Interval in milliseconds for the polling request to stay open.
This option sets the duration in milliseconds (ms) between MongoDB queries while long polling for notifications. It defaults to 500ms (1/2 a second). If you prefer fewer queries you can set this to a larger value, however, the queries are indexed queries on a small amount of data and shouldn't impact your app.
This option sets the duration of the long polling request in milliseconds. It defaults to 10000ms (10 seconds). This duration is typically a good balance between reducing overall server requests and avoiding timeouts from network intermediaries like proxy servers. It also helps in managing server resources efficiently by not keeping connections open excessively long and ensures a responsive user experience by providing timely updates without the overhead of constant querying.
The usage of
apos.notify differs slightly for server- vs client-side created notifications. In both cases, you need to pass the desired message string and an object of options. When using the method server-side, the first argument should be either the
req object or a user
await self.apos.notify(req, 'message', options, interpolation);
await apos.notify('message', options, interpolation);
The message will be interpolated by i18next if there is a corresponding localization key, or passed directly if no key is found. You can pass additional keys to be interpolated and added to the message using either an
interpolation object passed as the third argument, or as
The translation strings file:
options argument object, passed after the
message string, you can pass several different properties.
The value of the
type property dictates the styling of the notification. In the example above the
success type was used, but this property also accepts other values:
danger for irrevocable actions like deleting a file,
error for serious issues that need immediate attention,
warning for situations that might require caution or are potentially problematic, and
info for general notifications. If no type is specified, the default is set to
icon property takes the name of an already registered icon. This icon is displayed in the notification to the left of the message.
dismiss property takes either a boolean or integer representing the time in seconds. By default, notifications need to be dismissed manually by the user. If this property is set to
true, the notification will automatically disappear after 5 seconds. If passed an integer, the notification will disappear after that specified number of seconds.
classes option can take an optional array of additional class names that should be added to the notification wrapper. If you wish to use the notification to trigger an event using
options.event, and do not want the user to see the notification itself you can pass
classes: [ 'apos-notification--hidden' ] in the options object.
return option takes a boolean and defaults to
false. If set to true, invoking a notification returns an object containing the
noteId property. The value of this property can be used to retrieve details about the notification from the
aposNotifications collection of the database.
buttons property allows for the display of one or more buttons within the notification. It takes an array of objects with each having at least
type properties. Currently, the
type property only takes
event as a value. The
label property takes an i18n string that will be displayed to the user. The
name property takes the name of an event that will be emitted when the button is clicked. Modules can listen for this on the client-side using
apos.bus.$on(<name-value>, callback);. An optional
data property can be used to pass an object to the module receiving the bus event. Clicking on a button will cause the notification to close.
In the browser, we could have functionality that allows users to add or delete comments on an article.
If the user deletes their comment it triggers the
deleteComment() method. This then presents a notification with a button to undo that deletion. If the user clicks the button,
undoDeleteComment is emitted on the bus along with the
commentId as the
data object payload. This bus event is picked up by the
$on listener, which uses the data
commentId to undelete the comment.
Much like the event triggered by clicking on the button, you can elect to trigger a bus even without the user having to click a button by using the
event property. This property takes an object with
name and an optional
data property, like the
buttons array objects. This event will be triggered as soon as the notification is presented to the user.