Metainformationen zur Seite

LoxBerry::Log::notify_ext

LoxBerry::Log::notify_ext( %params );

Creates an information or error notification with extended attributes. Use this function, if you want to store more information in your notification than a simple LoxBerry::Log::notify.

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.

notify_ext (ext for extended) allows you to store more than one attribute (the message) in a notification.

You can use the notification to transport more detailed information or settings from the sending side (the script calling notify_ext) to the receiver (the script or webinterface receiving the notification). Remember that the notification is still displayed as a number in the plugins overview page. The additional information should be read with get_notifications and parsed and displayed in a way that the user still can see the coherence between the notification bullet on the plugins page and the main page of your plugin.

So as in notify, the $package, $name and $message are mandatory parameters. To these parameters, add as many attributes you like. See the example how it works.

The $package is the owner of the notification. To show the notification bullet on the plugins page, this needs to be $lbpplugindir.

Inside the package, you can group your notifications by $name. For example, your plugin uses a cronjob and a daemon. Use "cronjob" and "daemon" as names to differentiate these notifications.

The $message is the text that is saved and displayed in the notification.

All additional parameters are stored to query them by get_notifications.

notify always saves the time you have called notify, so you don't need to place a timestamp in the message.

Case sensitivity

The parameter names PACKAGE, NAME, MESSAGE and SEVERITY are case-sensitive.

The content of PACKAGE and NAME is also case-sensitive. If you set the NAME => "Daemon", you have to query "Daemon" in get_notifications and get_notifications_html.

Parameter

Not all parameters are required. 

ParameterRequiredBeschreibung
PACKAGE x This is, where the message belongs to. In a plugin, always use the variable $lbpplugindir.
NAME x The notification group, this notification belongs to.
MESSAGE x The message to be sent.
SEVERITY If you omit this parameter, an informational notification (severity 6) is created.

If you specify the severity, use a level from 0 to 7 (see the log levels here: plugindatabase.dat)

Use 6 for info or 3 for error. Other levels currently are undefined.
LINK This optional parameter can be used to add a link with a "Details" button.

Setting the LINK parameter and filling it with an internal or external hyperlink, will show a "Details" button in the get_notifications_html page.
LOGFILE This optional parameter can be used to add a local path to a logfile.

get_notification_html will show a logfile button to directly open the logviewer, if the LOGFILE parameter is found.

Return value

Returns undef, if the call failed. Returns something else, if the request was successful.

The function will die a bad death with the plugins calling line in the error message, if the mandatory values are empty. The function will return <> undef, if there was another problem to set the notification. So only programming errors will kill the execution, but not errors inside the function.

Usage

use LoxBerry::Log;
 
my %notification = (
            PACKAGE => $lbpplugindir,                        # Mandatory
            NAME => "daemon",                                # Mandatory         
            MESSAGE => "error connecting to the Miniserver", # Mandatory
            SEVERITY => 3,
            fullerror => "Access is denied: " . $error,
            msnumber => 1,
            LOGFILE => $log->filename
    );
my $status = LoxBerry::Log::notify_ext( \%notification );
 
# Error handling
if (! $status) {
    print STDERR "Error setting notification.";
}

All the parameters are stored and will be returned in a hash if you query the notifications.

It is important to send the hashref (not the hash) to the notify_ext function. Use the \%hash syntax to deliver the hashref.

Using the LOGFILE parameter will add a logfile button in the notification view.

Infos

Please see the Notification tips and tricks