Notifications are the nice bullets (in Austria we would say, they look like Knödel) that are displayed on the icons and the navigation bar.
There are two different colors:
- Blue is used for information level.
- Red is used for errors
For example, if LoxBerry Update is enabled with scheduled automatic updates, it will give you a blue bullet if the update was processed successfully in the background, but gives you a red bullet if the update failed.
Notifications are cumulative, that means every new notification by default does not delete older notifications.
For all features you have to use LoxBerry::Log:
Currently every plugin can access all notifications, also from other plugins and from the system. Misusing delete_notifications could also delete foreign notifications from plugins and system.
Please be careful setting and deleting notifications.
This behaviour is provisorily as we trust plugin developers, but may change to be locked down to own plugin notifications if problems are reported.
Create an information notification (blue)
The first parameter is the so-called Package name. For Plugins, this is is always the plugin foldername, therefore, simply forward the global
The second parameter is a name for the notification group. With the functions to read the notifications, you can filter by the notification group. For example, your plugin, could have a notification group used by a cronjob of your plugin, and another group for a daemon script.
The third parameter is the message of your notification. The messages can be loaded with the reading functions.
Neither in the name nor in the message you need to store the occurence date/time, as every notification stores it's time itself.
If you need to have only one notification in the group, first set the notification, then use delete_notifications with the keep-latest parameter.
Create an error notification (red)
This is quite the same as an information notify, but has the fourth parameter to signal an error:
The fourth parameter 1 signals an error notify.
Show your notifications on the top of your page
We've implemented an entirely integrated feature to show your notifications on top of your page with a single command.
Place this command directly after calling the lbheader printing function, or, in legacy code, after printing the header template:
undef as the second parameter (the notification name) will show all notifications of your plugin.
If you only want to show errors or information notification, add a third parameter:
'infos' filter for that notifications. No third parameter will show both.
Notifications on the start page (plugin overview)
Using $lbpplugindir as package, info and error bullets are automatically shown on LoxBerry's start page at your plugin icon.
Notification in the navigation bar
If you use LoxBerry's Navigation Bar, you can add a key to the $navbar variable to directly show the notification bullets in your navigation bar at the appropriate tab. Each notification "name" can match to one tab.
There are several functions to read notifications for different demands.
Get the number of current notifications
This function only returns a count of if any notification exists. It does not return any notification metadata.
Parameters 1 and 2 are, like in notify, the Package and the name.
You'll get returned the number of errors, informations and the sum of them.
You can query all of your notifications with one parameter
$lbpplugindir, or only for a specific group with parameters
$lbpplugindir and the group name.
Returned is an array with a hashref:
|CONTENTRAW||The message of the notification|
|CONTENTHTML||The message HTML-encoded. Linefeeds are converted to <br>.|
|SEVERITY||3 is an error, 6 is information. Other levels are reserved for future use.|
|<attribute1>||This are your own attributes inserted by notify_ext|
|<attribute2>||This are your own attributes inserted by notify_ext|
This attributes are automatically added to your notification
You can use them the same way as the other attributes.
|DATEISO||This is the ISO 6801 time format (2018-02-18T14:34:56). Use |
|DATESTR||This is a date string in the format|
|KEY||The key is a unique key that represents this notification.|
|_ISPLUGIN||This parameter is set, if |
|_ISSYSTEM||This parameter is set, if |
The returned array is sorted by notification date, descending, so the latest notification comes first.
You can alternatively delete all notifications of a package or group, or delete all but the least one.
Delete all notifications
This will delete all notifications for your plugin and the group "notificationname".
Delete all but least notification
Simply add a third parameter 1 to keep the latest notification:
In some situations it makes no sense to keep all notifications cumulative. Therefore, you can set and then delete older notifications with first notify, and then delete_notifications with the keep-latest parameter.
You also can delete all notifications of your plugin by omitting the notification name parameter (the second one):
Delete a single notification
This function is available starting with LoxBerry V1.0.3. If you use that function, set this minimum version in your plugin.cfg.
get_notifications returns a KEY value. Use this KEY value to delete this specific notification: