Notifications¶
- There are two ways to send notifications in Elgg:
- Instant notifications
- Event-based notifications send using a notifications queue
Contents
Instant notifications¶
The generic method to send a notification to a user is via the function notify_user(). It is normally used when we want to notify only a single user. Notification like this might for example inform that someone has liked or commented the user’s post.
The function usually gets called in an action file.
Example:¶
In this example a user ($user
) is triggering an action to rate a post created
by another user ($owner
). After saving the rating (ElggAnnotation $rating
)
to database, we could use the following code to send a notification about the new
rating to the owner.
// Subject of the notification
$subject = elgg_echo('ratings:notification:subject', array(), $owner->language);
// Summary of the notification
$summary = elgg_echo('ratings:notification:summary', array($user->name), $owner->language);
// Body of the notification message
$subject = elgg_echo('ratings:notification:body', array(
$user->name,
$owner->name,
$rating->getValue() // A value between 1-5
), $owner->language);
$params = array(
'object' => $rating,
'action' => 'create',
'summary' => $summary
);
// Send the notification
notify_user($owner->guid, $user->guid, $subject, $body, $params);
Note
The language used by the recipient isn’t necessarily the same as the language of the person
who triggers the notification. Therefore you must always remember to pass the recipient’s
language as the third parameter to elgg_echo()
.
Note
The 'summary'
parameter is meant for notification plugins that only want to display
a short message instead of both the subject and the body. Therefore the summary should
be terse but still contain all necessary information.
Enqueued notifications¶
On large sites there may be many users who have subscribed to receive notifications about a particular event. Sending notifications immediately when a user triggers such an event might remarkably slow down page loading speed. This is why sending of such notifications shoud be left for Elgg’s notification queue.
New notification events can be registered with the elgg_register_notification_event() function. Notifications about registered events will be sent automatically to all subscribed users.
Example¶
Tell Elgg to send notifications when a new object of subtype “photo” is created:
/**
* Initialize the photos plugin
*/
function photos_init() {
elgg_register_notification_event('object', 'photo', array('create'));
}
Note
In order to send the event-based notifications you must have the one-minute CRON interval configured.
Contents of the notification message can be defined with the
'prepare', 'notification:[action]:[type]:[subtype]'
hook.
Example¶
Tell Elgg to use the function photos_prepare_notification()
to format
the contents of the notification when a new objects of subtype ‘photo’ is created:
/**
* Initialize the photos plugin
*/
function photos_init() {
elgg_register_notification_event('object', 'photo', array('create'));
elgg_register_plugin_hook_handler('prepare', 'notification:create:object:photo', 'photos_prepare_notification');
}
/**
* Prepare a notification message about a new photo
*
* @param string $hook Hook name
* @param string $type Hook type
* @param Elgg_Notifications_Notification $notification The notification to prepare
* @param array $params Hook parameters
* @return Elgg_Notifications_Notification
*/
function photos_prepare_notification($hook, $type, $notification, $params) {
$entity = $params['event']->getObject();
$owner = $params['event']->getActor();
$recipient = $params['recipient'];
$language = $params['language'];
$method = $params['method'];
// Title for the notification
$notification->subject = elgg_echo('photos:notify:subject', array($entity->title), $language);
// Message body for the notification
$notification->body = elgg_echo('photos:notify:body', array(
$owner->name,
$entity->title,
$entity->getExcerpt(),
$entity->getURL()
), $language);
// Short summary about the notification
$notification->summary = elgg_echo('photos:notify:summary', array($entity->title), $language);
return $notification;
}
Note
Make sure the notification will be in the correct language by passing
the reciepient’s language into the elgg_echo()
function.
Registering a new notification method¶
By default Elgg has two notification methods: email and the bundled site_notifications plugin. You can register a new notification method with the elgg_register_notification_method() function.
Example:¶
Register a handler that will send the notifications via SMS.
/**
* Initialize the plugin
*/
function sms_notifications_init () {
elgg_register_notification_method('sms');
}
After registering the new method, it will appear to the notification
settings page at www.example.com/notifications/personal/[username]
.
Sending the notifications using your own method¶
Besides registering the notification method, you also need to register
a handler that takes care of actually sending the SMS notifications.
This happens with the 'send', 'notification:[method]'
hook.
Example:¶
/**
* Initialize the plugin
*/
function sms_notifications_init () {
elgg_register_notification_method('sms');
elgg_register_plugin_hook_handler('send', 'notification:sms', 'sms_notifications_send');
}
/**
* Send an SMS notification
*
* @param string $hook Hook name
* @param string $type Hook type
* @param bool $result Has anyone sent a message yet?
* @param array $params Hook parameters
* @return bool
* @access private
*/
function sms_notifications_send($hook, $type, $result, $params) {
/* @var Elgg_Notifications_Notification $message */
$message = $params['notification'];
$recipient = $message->getRecipient();
if (!$recipient || !$recipient->mobile) {
return false;
}
// (A pseudo SMS API class)
$sms = new SmsApi();
return $sms->send($recipient->mobile, $message->body);
}
Subscriptions¶
In most cases Elgg core takes care of handling the subscriptions, so notification plugins don’t usually have to alter them.
- Subscriptions can however be:
- Added using the elgg_add_subscription() function
- Removed using the elgg_remove_subscription() function
It’s possible to modify the recipients of a notification dynamically
with the 'get', 'subscriptions'
hook.
Example:¶
/**
* Initialize the plugin
*/
function discussion_init() {
elgg_register_plugin_hook_handler('get', 'subscriptions', 'discussion_get_subscriptions');
}
/**
* Get subscriptions for group notifications
*
* @param string $hook 'get'
* @param string $type 'subscriptions'
* @param array $subscriptions Array containing subscriptions in the form
* <user guid> => array('email', 'site', etc.)
* @param array $params Hook parameters
* @return array
*/
function discussion_get_subscriptions($hook, $type, $subscriptions, $params) {
$reply = $params['event']->getObject();
if (!elgg_instanceof($reply, 'object', 'discussion_reply', 'ElggDiscussionReply')) {
return $subscriptions;
}
$group_guid = $reply->getContainerEntity()->container_guid;
$group_subscribers = elgg_get_subscriptions_for_container($group_guid);
return ($subscriptions + $group_subscribers);
}