Skip to end of metadata
Go to start of metadata

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:

use LoxBerry::Log;
use LoxBerry::Log;

Plugin developers

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.

See also 

Debugging of notifications

Create notifications

Create an information notification (blue)

Create an information
my $message = "There is an important information for you!";

notify ( $lbpplugindir, "notificationname", $message);

The first parameter is the so-called Package name. For Plugins, this is is always the plugin foldername, therefore, simply forward the global $lbpplugindir variable.

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:

Create an error notify
my $message = "Some error occured! Check the log!";
notify ( $lbpplugindir, "notificationname", $message, 1);

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:

use LoxBerry::Log;

LoxBerry::Web::lbheader($template_title, $helplink, $helptemplate);

# Print your plugins notifications with name daemon.
print LoxBerry::Log::get_notifications_html($lbpplugindir, 'daemon');

print $maintemplate->output();

get_notifications_html creates the ready html code including JavaScript to clear your notifications.

Using 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:

print LoxBerry::Log::get_notifications_html($lbpplugindir, 'daemon', 'errors');
print LoxBerry::Log::get_notifications_html($lbpplugindir, 'daemon', 'infos');

The keywords 'errors' and '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.

See Navigation Bar (Perl)Navigation Bar (PHP)

Reading notifications

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.

Number of current notifications
my ($check_err, $check_ok, $check_sum) = get_notification_count( $lbpplugindir, "notificationname");

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.

Get notifications

Get notifications
# For the hole package
my @notifications = get_notifications( $lbpplugindir); 
# Filtered to a specific notification group
my @notifications = get_notifications( $lbpplugindir, "notificationname"); 

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:

Hash KeyContent
PACKAGEPackage name
NAMEGroup name
CONTENTRAWThe message of the notification
CONTENTHTMLThe message HTML-encoded. Linefeeds are converted to <br>.
SEVERITY3 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
System added

This attributes are automatically added to your notification

You can use them the same way as the other attributes.

DATEISOThis is the ISO 6801 time format (2018-02-18T14:34:56). Use Time::Piece to convert.
DATESTRThis is a date string in the format %d.%m.%Y %H:%M
KEYThe key is a unique key that represents this notification.
_ISPLUGINThis parameter is set, if notify or notify_ext detected a plugin notification
_ISSYSTEMThis parameter is set, if notify or notify_ext detected a system notification

Usage example:

Work with notifications
# Filtered to a specific notification group
my @notifications = get_notifications( $lbpplugindir, "notificationname"); 

for my $notification (@notifications ) {
	if ( $notification->{SEVERITY} == 3 ) {
		print STDERR "An error occured at $notification->{DATESTR}."; 
 	} elsif ( $notification->{SEVERITY} == 6 ) {
 		print STDERR "There is an information at $notification->{DATESTR}.";

The returned array is sorted by notification date, descending, so the latest notification comes first.

Delete notifications

You can alternatively delete all notifications of a package or group, or delete all but the least one.

Delete all notifications

Delete all notifications
delete_notifications( $lbpplugindir, "notificationname" ); 

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:

Delete all but least notification
delete_notifications( $lbpplugindir, "notificationname", 1 ); 

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):

Create and delete
notify ( $lbpplugindir, "notificationname", $message);
delete_notifications( $lbpplugindir, "notificationname", 1 ); 

Delete a single notification

LoxBerry 1.0.3

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:

Create and delete
delete_notification_key ( $key ); 

Further infos

Notification tips and tricks

  • No labels