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

Contenus

Notifications instantanées
Notifications en file d’attente
Enregistrement d’une nouvelle méthode de notification
Envoyer des notifications à l’aide de votre propre méthode
Abonnements

Notifications instantanées ¶

La méthode générique pour envoyer une notification à un utilisateur utilise la fonction `notify_user()`__. Celle-ci devrait être principalement utilisée lorsque nous voulons notifier un seul utilisateur. Une notification comme celle-ci peut, par exemple, informer que quelqu’un a aimé ou commenté la publication de l’utilisateur.

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 sur la nouvelle note au propriétaire.

// 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
$body = 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

La langue utilisée par le destinataire n’est pas nécessairement la même que celle de la personne qui déclenche la notification. Par conséquent, vous devez toujours penser à transmettre la langue du destinataire en tant que troisième paramètre à elgg_echo().

Note

Le paramètre 'summary' est destiné aux plugins de notification qui ne souhaitent afficher qu’un message court au lieu du sujet et du corps. Par conséquent, le résumé doit être laconique, mais toujours contenir toutes les informations nécessaires.

Notifications en file d’attente ¶

Sur les grands sites, il peut y avoir de nombreux utilisateurs qui se sont abonnés pour recevoir des notifications lors d’un événement particulier. L’envoi immédiat de notifications lorsqu’un utilisateur déclenche un tel événement peut ralentir considérablement la vitesse de chargement des pages. C’est pourquoi l’envoi de ces notifications devrait être mis dans la file d’attente de notification de Elgg.

De nouveaux événements de notification peuvent être enregistrés avec la fonction ``elgg_register_notification_event()``__. Les notifications concernant les événements enregistrés seront envoyées automatiquement à tous les utilisateurs abonnés.

Voici le workflow du système de notifications :

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)

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

Lorsque le gestionnaire du hook plugin pour l’intervalle d’une minute est déclenché, l’événement est pris dans la file d’attente et est traité

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>

Les plugins peuvent modifier les abonnements avec le hook [get, subscriptions]

Les plugins peuvent empêcher le traitement de la file d’attente des notifications avec le hook [send:before, notifications]

Les plugins peuvent modifier les paramètres de notification avec le hook [prepare, notification]

Les plugins peuvent modifier le sujet, le message et le résumé de la notification avec le hook [prepare, notification:<action>:<type>:<subtype>]

Les plugins peuvent à mettre en forme le sujet, le message et le résumé de la notification pour chaque méthodes d’envoi individuelle avec le hook [format, notification:<method>]

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

Les plugins peuvent prendre la main sur chaque notification individuelle ou en bloquer l’envoi avec le hook [send, notification:<method>]

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

Exemple¶

Dites à 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', array('create'));
}

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 le hook 'prepare', 'notification:[action]:[type]:[subtype]'.

Exemple¶

Dites à 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', 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

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

Enregistrement d’une nouvelle méthode de notification ¶

Par défaut, Elgg dispose de deux méthodes de notification : le courrier électronique et le plugin site_notifications. 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.exemple.com/notifications/personal/[username].

Envoyer des notifications à l’aide de votre propre méthode ¶

En plus d’enregistrer la méthode de notification, vous devez également enregistrer un gestionnaire qui s’occupe de l’envoi des notifications SMS. Cela se fait avec le hook 'send', 'notification:[method]'.

Exemple :¶

/**
 * 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);
}

Abonnements ¶

Dans la plupart des cas, Elgg core 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ées à l’aide de la fonction `elgg_add_subscription()`__
Supprimées à l’aide de la fonction `elgg_remove_subscription()`__

Il est possible de modifier dynamiquement les destinataires d’une notification avec le hook 'get', 'subscriptions'.

Exemple :¶

/**
 * 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);
}

Notifications¶

Notifications instantanées¶

Exemple :¶

Notifications en file d’attente¶

Exemple¶

Exemple¶

Enregistrement d’une nouvelle méthode de notification¶

Exemple :¶

Envoyer des notifications à l’aide de votre propre méthode¶

Exemple :¶

Abonnements¶

Exemple :¶

Notifications instantanées ¶

Notifications en file d’attente ¶

Enregistrement d’une nouvelle méthode de notification ¶

Envoyer des notifications à l’aide de votre propre méthode ¶

Abonnements ¶