Notifications

Il existe deux manières d’envoyer des notifications dans Elgg :

• Notifications instantanées

• Les notifications basées sur les événements sont envoyées à l’aide d’une file d’attente de notifications

Notifications instantanées

La méthode générique pour envoyer une notification à un utilisateur est la fonction elgg_notify_user(). Elle est généralement utilisée pour notifier un seul utilisateur. Une telle notification peut, par exemple, informer qu’un utilisateur a aimé ou commenté sa publication.

La fonction est habituellement appelée dans un fichier d”action.

Exemple :

Dans cet exemple, un utilisateur ($user) déclenche une action pour noter une publication créée par un autre utilisateur ($owner). Après avoir enregistré la note (ElggAnnotation $rating) dans la base de données, nous pourrions utiliser le code suivant pour envoyer une notification concernant cette nouvelle note au propriétaire.

// register a notification handler
elgg_register_notification_event('annotation', 'rating', 'rate', MyNotificationHandler::class);

// The notification handler
class MyNotificationHandler extends \Elgg\Notifications\InstantNotificationEventHandler {

    protected function getNotificationSubject(\ElggUser $recipient, string $method): string {
        return elgg_echo('ratings:notification:subject');
    }

    protected function getNotificationSummary(\ElggUser $recipient, string $method): string {
        return elgg_echo('ratings:notification:summary', [
            $this->getEventActor()->getDisplayName(),
        ]);
    }

    protected function getNotificationBody(\ElggUser $recipient, string $method): string {
        $object = $this->event->getObject();

        return elgg_echo('ratings:notification:body', [
            $this->getEventActor()->getDisplayName(),
            $object->getEntity()->getOwnerEntity()->getDisplayName(),
            $rating->getValue() // A value between 1-5
        ]);
    }
}

// now notify the owner
$owner->notify('rate', $rating, [], $user);

Note

Lors du traitement des notifications, la langue est automatiquement basculée sur la langue du destinataire.

Notifications en file d’attente

Sur les grands sites, de nombreux utilisateurs peuvent s’abonner aux notifications d’un événement particulier. Envoyer des notifications immédiatement lorsqu’un utilisateur déclenche un tel événement peut ralentir considérablement le chargement des pages. C’est pourquoi l’envoi de ces notifications doit être réservé à la file d’attente des notifications d’Elgg.

De nouveaux événements de notification peuvent être enregistrés avec la fonction elgg_register_notification_event() ou dans la configuration de elgg-plugin. Des notifications sur les événements enregistrés seront envoyées automatiquement à tous les utilisateurs abonnés.

Voici le workflow du système de notifications :

1. Quelqu’un effectue une action qui déclenche un événement au sein de Elgg

   • L’action peut être create, update ou delete

   • La cible de l’action peut être n’importe quelle instance de la classe ElggEntity (par exemple un article de blog)

2. Le système de notifications enregistre cet événement dans une file d’attente de notifications dans la base de données

3. Lorsque le gestionnaire d’événements pour l’intervalle d’une minute est déclenché, l’événement est retiré de la file d’attente et traité.

4. Les abonnements sont récupérés pour l’utilisateur qui a déclenché l’événement

   • Par défaut, ceci comprend tous les utilisateurs qui ont activé au moins une méthode de notification pour les utilisateurs via www.site.com/notifications/personal/<username>

5. Les plugins sont autorisés à modifier les abonnements en utilisant l’événement [get, souscriptions]

6. Les plugins sont autorisés à interrompre le traitement de la file d’attente des notifications avec l’événement [send:before, notifications]

7. Les plugins sont autorisés à modifier les paramètres de notification avec l’événement [send:before, notifications]

8. Les plugins sont autorisés à modifier le subject/message/summary de la notification avec l’événement [prepare, notification:<action>:<type>:<subtype>]

9. Les plugins sont autorisés à formater le sujet/message/résumé de notification pour des méthodes de livraison individuelles avec l’événement [format, notification:<method>]

10. Les notifications sont envoyées à chaque abonné en utilisant les méthodes qu’il a choisies

    • Les plugins peuvent remplacer ou empêcher l’envoi de chaque notification individuelle avec l’événement [send, notification:<method>]

11. L’événement [send:after, notifications] est déclenché pour l’événement après que toutes les notifications ont été envoyées

Exemple d’enregistrement d’un événement de notification

Indiquez à Elgg d’envoyer des notifications lorsqu’un nouvel objet de sous-type photo est créé :

/**
 * Initialize the photos plugin
 */
function photos_init() {
        elgg_register_notification_event('object', 'photo');
}

Ou dans elgg-plugin.php

'notifications' => [
        'object' => [
                'photo' => [
                        'create' => [
                                Elgg\Notifications\NotificationEventHandler::class => [],
                        ],
                ],
        ],
],

Note

Pour envoyer les notifications lors des événements, vous devez configurer l’intervalle CRON d’une minute.

Le contenu du message de notification peut être défini avec l’événement 'prepare', 'notification:[action]:[type]:[subtype]'.

Exemple d’enregistrement d’un événement de notification personnalisé

Indiquer à Elgg d’envoyer des notifications lorsqu’un nouvel objet de sous-type album est créé :

// in the elgg-plugin.php
'notifications' => [
        'object' => [
                'photo' => [
                        'create' => PhotoAlbumCreateNotificationHandler::class, // this needs to be an extension of the \Elgg\Notifications\NotificationEventHandler class
                ],
        ],
],

//PhotoAlbumCreateNotificationHandler.php

class PhotoAlbumCreateNotificationHandler extends \Elgg\Notifications\NotificationEventHandler {

        /**
         * Overrule this function if you wish to modify the subscribers of this notification
         *
         * This will influence which subscribers are available in the 'get', 'subscribers' event
         */
        public function getSubscriptions(): array {
        }

        /**
         * Overrule this function if you wish to modify the subject of the notification
         *
         * A magic language key is checked for a default notification:
         * 'notification:<action>:<type>:<subtype>:subject'
         */
        protected function getNotificationSubject(\ElggUser $recipient, string $method): string {
        }

        /**
         * Overrule this function if you wish to modify the body of the notification
         *
         * A magic language key is checked for a default notification:
         * 'notification:<action>:<type>:<subtype>:body'
         */
        protected function getNotificationBody(\ElggUser $recipient, string $method): string {
        }

        /**
         * Overrule this function if you wish to modify the summary of the notification
         *
         * default: ''
         */
        protected function getNotificationSummary(\ElggUser $recipient, string $method): string {
        }

        /**
         * Overrule this function if you wish to modify the target url of the notification
         *
         * default: $event->object->getURL()
         */
        protected function getNotificationURL(\ElggUser $recipient, string $method): string {
        }

        /**
         * Overrule this function if you don't wish to allow the notification event to be configurable on the user notification settings page
         *
         * default: true
         */
        public static function isConfigurableByUser(): bool {
        }
}

Note

Lors du traitement des notifications, la langue est automatiquement basculée sur la langue du destinataire.

Multiple notification event handlers

It’s possible to have multiple notification handlers on the same event. This can be useful when you want to send a different message to different recipient.

// in the elgg-plugin.php
'notifications' => [
        'user' => [
                'user' => [
                        'ban' => [
                                UserBanNotification::class => [], // send a notification to the banned user
                                AdminBanNotification::class => [], // send a notification to site admins that the user was banned
                        ],
                ],
        ],
],

Exemple de contenu de notification personnalisé

Indique à Elgg d’utiliser la fonction photos_prepare_notification() pour formater le contenu de la notification quand un nouvel objet de sous-type “photo” est créé :

/**
 * Initialize the photos plugin
 */
function photos_init() {
    elgg_register_notification_event('object', 'photo');
    elgg_register_event_handler('prepare', 'notification:create:object:photo', 'photos_prepare_notification');
}

/**
 * Prepare a notification message about a new photo
 *
 * @param \Elgg\Event $event 'prepare', 'notification:create:object:photo'

 * @return \Elgg\Notification\Notification
 */
function photos_prepare_notification(\Elgg\Event $event) {
    $notification_event = $event->getParam('event');

    $entity = $notification_event->getObject();
    $owner = $notification_event->getActor();
    $recipient = $event->getParam('recipient');
    $language = $event->getParam('language');
    $method = $event->getParam('method');

    /* @var $notification \Elgg\Notification\Notification */
    $notification = $event->getValue();

    // Title for the notification
    $notification->subject = elgg_echo('photos:notify:subject', [$entity->getDisplayName()], $language);

    // Message body for the notification
    $notification->body = elgg_echo('photos:notify:body', [
        $owner->getDisplayName(),
        $entity->getDisplayName(),
        $entity->getExcerpt(),
        $entity->getURL()
    ], $language);

    // Short summary about the notification
    $notification->summary = elgg_echo('photos:notify:summary', [$entity->getDisplayName()], $language);

    return $notification;
}

Note

Assurez-vous que la notification sera dans la bonne langue en passant la langue du destinataire dans la fonction elgg_echo().

Salutation et signature de la notification

Par défaut, Elgg ajoute une salutation au corps de toutes les notifications sortantes. Une signature est également ajoutée. Vous n’aurez donc pas besoin d’ajouter de texte comme Bonjour administrateur ou Cordialement, votre aimable administrateur de site au corps de vos notifications. Si, pour une raison quelconque, vous ne souhaitez pas que cette fonctionnalité soit utilisée, vous pouvez la bloquer en définissant le paramètre de notification add_salutation sur false. Vous pouvez le faire dans les paramètres de la fonction elgg_notify_user() ou dans l’événement prepare, notifications. Vous pouvez modifier les textes de salutation et de signature dans les traductions.

Vous pouvez également personnaliser la salutation en remplaçant la vue notifications/elements/salutation. La signature peut être personnalisée en remplaçant la vue notifications/elements/sign-off.

Méthodes de notification

Par défaut, Elgg propose trois méthodes de notification : email, delayed_email et le plugin site_notifications fourni avec Elgg.

E-mail

Enverra une notification par e-mail au destinataire.

E-mail différé

Enregistre les notifications pour les envoyer dans un e-mail groupé à l’intervalle configuré par le destinataire (quotidien ou hebdomadaire).

La disponibilité de cette méthode d’envoi peut être configurée par l’administrateur du site dans la section Paramètres du site.

La mise en page de l’e-mail groupé peut être personnalisée en remplaçant la vue email/delayed_email/plain_text pour la partie en texte brut de l’e-mail et email/delayed_email/html pour la partie HTML de l’e-mail.

Notification sur le site

Affichera la notification sur le site.

Enregistrement d’une nouvelle méthode de notification

Vous pouvez enregistrer une nouvelle méthode de notification avec la fonction elgg_register_notification_method().

Exemple :

Enregistrez un gestionnaire qui enverra les notifications par SMS.

/**
 * Initialize the plugin
 */
function sms_notifications_init() {
        elgg_register_notification_method('sms');
}

Après avoir enregistré la nouvelle méthode, celle-ci apparaîtra sur la page des paramètres de notification à l’adresse www.example.com/notifications/personal/[username].

Envoyer des notifications avec votre propre méthode

Outre l’enregistrement de la méthode de notification, vous devez également enregistrer un gestionnaire qui se charge d’envoyer réellement les notifications SMS. Cela se produit avec l’événement 'send', 'notification:[method]'.

Exemple :

/**
 * Initialize the plugin
 */
function sms_notifications_init () {
        elgg_register_notification_method('sms');
        elgg_register_event_handler('send', 'notification:sms', 'sms_notifications_send');
}

/**
 * Send an SMS notification
 *
 * @param \Elgg\Event $event 'send', 'notification:sms'
 *
 * @return bool
 * @internal
 */
function sms_notifications_send(\Elgg\Event $event) {
        /* @var \Elgg\Notifications\Notification $message */
        $message = $event->getParam('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);
}

Abonnements

Dans la plupart des cas, le noyau de Elgg s’occupe de la gestion des abonnements, de sorte que les plugins de notification n’ont généralement pas besoin de les modifier.

Les abonnements peuvent toutefois être :

• Ajoutés à l’aide de la fonction \ElggEntity::addSubscription()

• Supprimés à l’aide de la fonction \ElggEntity::removeSubscription()

Il est possible de modifier dynamiquement les destinataires d’une notification avec l’événement 'get', 'subscriptions'.

Exemple :

/**
 * Initialize the plugin
 */
function discussion_init() {
        elgg_register_event_handler('get', 'subscriptions', 'discussion_get_subscriptions');
}

/**
 * Get subscriptions for group notifications
 *
 * @param \Elgg\Event $event 'get', 'subscriptions'
 *
 * @return void|array
 */
function discussion_get_subscriptions(\Elgg\Event $event) {
        $reply = $event->getParam('event')->getObject();

        if (!$reply instanceof \ElggDiscussionReply) {
                return;
        }

        $subscriptions = $event->getValue();

        $group_guid = $reply->getContainerEntity()->container_guid;
        $group_subscribers = elgg_get_subscriptions_for_container($group_guid);

        return ($subscriptions + $group_subscribers);
}

Notifications en sourdine

Les notifications peuvent être désactivées afin de ne plus recevoir de notifications, par exemple pour ne plus recevoir de notifications concernant de nouveaux commentaires sur une discussion.

Afin de désactiver les notifications, appelez \ElggEntity::muteNotifications($user_guid) le $user_guid est par défaut l’utilisateur actuellement connecté. Cela entraînera la suppression de tous les abonnements sur l’entité et un indicateur spécial sera défini pour savoir que les notifications sont désactivées.

Les règles de désactivation sont appliquées après que les abonnés d’un événement de notification ont été demandées et appliquées pour les entités suivantes de l’événement de notification : - l’acteur de l’événement \Elgg\Notifications\NotificationEvent::getActor() - l’entité objet de l’événement \Elgg\Notifications\NotificationEvent::getObject() - l’entité conteneur de l’objet de l’événement \Elgg\Notifications\NotificationEvent::getObject()::getContainerEntity() - l’entité propriétaire de l’objet de l’événement \ Elgg\Notifications\NotificationEvent::getObject()::getOwnerEntity()

Pour réactiver les notifications, appelez \ElggEntity::unmuteNotifications($user_guid) le $user_guid est par défaut l’utilisateur actuellement connecté.

Pour vérifier si un utilisateur a les notifications désactivées, appelez \ElggEntity::hasMutedNotifications($user_guid) le $user_guid est par défaut l’utilisateur actuellement connecté.

Page d’aide

Une page d’aide a été ajoutée qui peut être liée (par exemple dans un pied de page d’e-mail) pour gérer la désactivation d’une notification particulière.

La page doit être obligatoirement signée et utiliser la route notifications:mute qui nécessite : - entity_guid l’entité sur laquelle porte la notification - recipient_guid le destinataire de la notification

Désactiver temporairement les notifications

Les utilisateurs peuvent désactiver temporairement toutes les notifications en accédant aux paramètres de notification et en définissant une date de début et de fin pour la période pour laquelle ils ne souhaitent pas recevoir de notifications.

Paramètres de notification

Vous pouvez stocker et récupérer les paramètres de notification des utilisateurs avec \ElggUser::setNotificationSetting() et \ElggUser::getNotificationSettings().

// Setting a notification preference
// notification method: mail
// notification is enabled
// for the purpose 'group_join' (when omitted this is 'default')
$user->setNotificationSetting('mail', true, 'group_join');

// retrieving the preference
$settings = $user->getNotificationSettings('group_join');
// this wil result in an array with all the current notification methods and their state like:
// [
//      'mail' => true,
//      'site' => false,
//      'sms' => false,
// ]

Lorsqu’un utilisateur n’a pas encore de paramètre distinct de celui par défaut, le système revient au paramètre de notification “default”.

Gestion des notifications

Lorsqu’une entité possède la capacité subscribable, les éléments de menu sont automatiquement ajoutés au menu title``afin de gérer l'abonnement. Cela nécessite que l'entité soit fournie à la page pour être transmise au menu ``title.