Notification

class plinth.notification.Notification(*args: Any, **kwargs: Any)

API to create persistent global notifications to users.

The number of notifications is shown on the top navigation bar of every page that the user loads. On clicking the notification icon, a full list of notifications is shown as a drop down that works on both on Desktop and Mobile interfaces.

The notification API provides the following functionality.

• Store the notifications on disk and persist them across restarts.

• Update a notification for any of its stored details.

• Show icon and name of the app that shows the notification.

• Present the notification title and message.

• Present actions that user can perform on the notification.

• Allow for full customization of content and actions of the notification. This allows for use cases such as showing progress bar. This is done by allowing a custom template to be used for rendering.

• Internationalization and localization of displayed notification.

• Allow the notification to be dismissed and resurrected after dismissal.

• Store arbitrary data as a dictionary along with the notification. This data is used for formatting localized strings and for rendering the custom template.

• Limit a notification to a group of users or to a single user.

• Retrieve a notification using specific string identifier.

• Iterate all the notifications.

• Filter notifications by app that created them, by whether the notification meant for a particular user and by whether a notification is dismissed or not.

• Provide a convenient way to obtain the context for rendering templates that intend to show notifications.

This class is a wrapper over Notification model to provide a simplified API. So, all of the Django model API is available on the class. The following fields are present in the model:

‘id’ is a unique string identifier for the notification and acts as the primary key for the stored database table. Only the following chars are currently allowed: A-Z, a-z, 0-9, - and =. If other chars must be used, it is recommended to use base32 encoding.

‘app_id’ is the unique ID of the app showing the notification.

‘severity’ is a string indicating the severity of the notification which can take one of the following values: ‘exception’, ‘error’, ‘warning’, ‘info’ and ‘debug’.

‘title’ is a user visible string that is the main heading of the notification. ‘title’ may be used to show a summary of notifications even ‘body_template’ is used for customization. So, it is mandatory. The user who requested the operation that caused the notification may be different from the user that sees the notification. Each user wishes to see the notification in their own locale. This string is stored to the disk as it is. It is translated and then formatted with ‘data’ dictionary just before showing it to the user. So, it must be marked for translation with (u)gettext_noop but must not be translated using (u)gettext or similar methods.

‘message’ is a user visible string that is the main body of the notification. It is formatted as a single paragraph. It is not used and must not be provided when ‘body_template’ is provided. It must be marked for translation but not translated similar to ‘title’.

‘actions’ is a list of dictionaries containing information about what operations, such as dismiss, that the user may perform on the notification. When not provided, no actions are shown and the notification can’t be dismissed. It is not used and must not be provided when ‘body_template’ is provided. When ‘body_template’ is provided, the template is expected to list its actions inside the template.

A example of ‘actions’ structure is as follows: [{‘type’: ‘dismiss’}, {‘type’: ‘link’, ‘class’: ‘warning’, ‘text’: ‘Cleanup’, ‘url’: ‘storage:index’}]. The ‘type’ parameter can be ‘dismiss’ or ‘link’. When ‘dismiss’ is the type, no other information is necessary and a simple action to dismiss the notification is provided. When the ‘type’ is ‘link’, a button is shown with label provided by ‘text’. The ‘text’ property is must be marked for translation but not translated similar to ‘title’. When the button is clicked, it will direct the user to the Django URL indicated by ‘url’. ‘class’ is used for CSS styling of the button. It can taken on any of the following values; ‘primary’, ‘default’, ‘warning’, ‘danger’, ‘success’, ‘info’.

‘body_template’ is the name of the Django template to use instead of ‘title’, ‘message’ and ‘actions’. It enables the the notification creator to go beyond the simple presentation offered by default and include rich content such as progress bars and forms inside a notification. The template itself is expected to contain a meaningful title, body and operations to be performed on the notification. It is an error to provide ‘body_template’ and any one of ‘message’ and ‘actions’ at the same time. ‘title’ may still be used when notifications are presented in other situations. The template is rendered with ‘data’ as it’s context. So, any key/values to be included in the context must become part of the ‘data’.

‘data’ is a custom dictionary that is serialized and stored along with the notification. It is has three purposes; to format the translated strings before showing to the user, to be used as context for rendering a custom template and to store any extra data associated with the notification on behalf of the it’s creator for future reference. Any string value in the dictionary, even in deeper levels, if prefixed by ‘translate:’ will be translated before being used.

‘created_time’ is a date/time field that is automatically populated when the notification is created.

‘last_update_time’ is a date/time field that is automatically modified when the notification is updated with newer properties, including changes to the ‘dismissed’ property.

‘user’ is the username of the account to which this notification should be shown to. When not provided or set to None, it means that the notification is meant for all the users (subject to ‘group’ restriction).

‘group’ is the group of users to which this notification should be shown to. When not provided or set to None, it means that the notification is meant for all the users (subject to ‘user’ restriction). If a user in the group dismisses the notification, it is no longer shown to other users. To let each user see the notification, create multiple notifications each restricted to a single user account instead.

‘dismissed’ is a boolean flag that indicates whether the notification has been dismissed by the user.

class Meta

Meta properties of the Notification model.

clean()

Perform additional validations on the model.

dismiss(should_dismiss=True)

Mark the notification as read or unread.

If ‘should_dismiss’ is True, the notification is dismissed else the notification is resurrected even after being dismissed.

static get(key)

Return a notification object with a matching ID.

static get_display_context(request, user)

Return a list of notifications meant for display to a user.

static list(key=None, app_id=None, user=None, dismissed=False)

Return a list of notifications for a user.

‘key’ if provided, return only notifications that match this value as their ‘id’.

‘app_id’ if provided, return only notifications that match this app_id.

‘user’ must be a Django request.user structure. If provided, only notifications that are meant for this user account specifically or meant for any of groups that this user belongs to will be returned.

‘dismissed’ is the a boolean flag or None. If not None, only notifications with the matching in their ‘dismissed’ field will be returned.

property severity_value

Return severity as a numeric value suitable for comparison.

static update_or_create(**kwargs)

Update a notification or create one if necessary.

‘id’ field will be used to retrieve the notification and all other fields values will be updated after retrieval. If not match is found, a new notification is created and returned.