Notification from plugins

e107 includes a 'notify' facility, whereby a specified user or user class can be notified when certain events take place.

An event has a 'trigger', and it is straightforward to add one or more triggers to a plugin.

The existing chatbox code is being used as an example.

There are two parts to causing notifications:

• Add a file e_notify.php to your plugin's root directory
• Generate the triggers in your code

The e_notify.php file

This simple file contains the information needed to link the triggers into the notification system, and to pre-process the details of the notification if necessary.

The following is a simple (single-trigger) e_notify.php file:

if (!defined('e107_INIT')) { exit; }

if(defined('ADMIN_PAGE') && ADMIN_PAGE === true)
{
	include_lan(e_PLUGIN."chatbox_menu/languages/".e_LANGUAGE."/".e_LANGUAGE.".php");
	$config_category = NT_LAN_CB_1;
	$config_events = array('cboxpost' => NT_LAN_CB_2);
}


if (!function_exists('notify_cboxpost')) {
	function notify_cboxpost($data) {
		global $nt;
		include_lan(e_PLUGIN."chatbox_menu/languages/".e_LANGUAGE."/".e_LANGUAGE.".php");
		$message = NT_LAN_CB_3.': '.USERNAME.' ('.NT_LAN_CB_4.': '.$data['ip'].' )<br />';
		$message .= NT_LAN_CB_5.':<br />'.$data['cmessage'].'<br /><br />';
		$nt -> send('cboxpost', NT_LAN_CB_6, $message);
	}
}

There are three key parts to this file:

• $config_category sets the title of the notify group in the Admin menu (particularly relevant when a plugin can generate more than one type of event)
• $config_events is an array which gives an internal name to each trigger ('cboxpost' here), and links it to a plain language text for display.
• function notify_cboxpost($data) is called by the notification manager to generate the required message. As we will see later, $data is in a coder-specified format, and this routine processes it to generate the message in a fairly self-explanatory way. This function is wrapped in a conditional to ensure it is only defined once. The name of the function is the concatenation of 'notify_' and the internal name of the event trigger, as specified in the previous point.

If defining multiple triggers, simply clone the above process - an additional entry in the $config_events array, and a separate function to handle the notify.

config_events are registered during a plugin install/upgrade, which you will need to do when adding or changing event names.

Triggering an event

To trigger a 'notify' event, simply insert a call to the event handler in your code:

$e_event -> trigger("cboxpost", $edata_cb);

The first parameter is the internal name of the trigger ( as defined earlier )

The second is data ( typically small ) which the function can make use of, such as part of the notification, to avoid additional sql queries. The data is passed by reference, so must be a variable, trying to set anything within the function brackets will cause an error.