notifications.rst 8.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279
  1. Notifications
  2. #############
  3. There are two ways to send notifications in Elgg:
  4. - Instant notifications
  5. - Event-based notifications send using a notifications queue
  6. .. contents:: Contents
  7. :local:
  8. :depth: 1
  9. Instant notifications
  10. =====================
  11. The generic method to send a notification to a user is via the function `notify_user()`__.
  12. It is normally used when we want to notify only a single user. Notification like
  13. this might for example inform that someone has liked or commented the user's post.
  14. The function usually gets called in an :doc:`action <actions>` file.
  15. __ http://reference.elgg.org/notification_8php.html#a9d8de7faa63baf2dcd5d42eb8f76eaa1
  16. Example:
  17. --------
  18. In this example a user (``$user``) is triggering an action to rate a post created
  19. by another user (``$owner``). After saving the rating (``ElggAnnotation $rating``)
  20. to database, we could use the following code to send a notification about the new
  21. rating to the owner.
  22. .. code-block:: php
  23. // Subject of the notification
  24. $subject = elgg_echo('ratings:notification:subject', array(), $owner->language);
  25. // Summary of the notification
  26. $summary = elgg_echo('ratings:notification:summary', array($user->name), $owner->language);
  27. // Body of the notification message
  28. $subject = elgg_echo('ratings:notification:body', array(
  29. $user->name,
  30. $owner->name,
  31. $rating->getValue() // A value between 1-5
  32. ), $owner->language);
  33. $params = array(
  34. 'object' => $rating,
  35. 'action' => 'create',
  36. 'summary' => $summary
  37. );
  38. // Send the notification
  39. notify_user($owner->guid, $user->guid, $subject, $body, $params);
  40. .. note::
  41. The language used by the recipient isn't necessarily the same as the language of the person
  42. who triggers the notification. Therefore you must always remember to pass the recipient's
  43. language as the third parameter to ``elgg_echo()``.
  44. .. note::
  45. The ``'summary'`` parameter is meant for notification plugins that only want to display
  46. a short message instead of both the subject and the body. Therefore the summary should
  47. be terse but still contain all necessary information.
  48. Enqueued notifications
  49. ======================
  50. On large sites there may be many users who have subscribed to receive notifications
  51. about a particular event. Sending notifications immediately when a user triggers
  52. such an event might remarkably slow down page loading speed. This is why sending
  53. of such notifications shoud be left for Elgg's notification queue.
  54. New notification events can be registered with the `elgg_register_notification_event()`__
  55. function. Notifications about registered events will be sent automatically to all
  56. subscribed users.
  57. __ http://reference.elgg.org/notification_8php.html#af7a43dcb0cf13ba55567d9d7874a3b20
  58. Example
  59. -------
  60. Tell Elgg to send notifications when a new object of subtype "photo" is created:
  61. .. code-block:: php
  62. /**
  63. * Initialize the photos plugin
  64. */
  65. function photos_init() {
  66. elgg_register_notification_event('object', 'photo', array('create'));
  67. }
  68. .. note::
  69. In order to send the event-based notifications you must have the one-minute
  70. :doc:`CRON </admin/cron>` interval configured.
  71. Contents of the notification message can be defined with the
  72. ``'prepare', 'notification:[action]:[type]:[subtype]'`` hook.
  73. Example
  74. -------
  75. Tell Elgg to use the function ``photos_prepare_notification()`` to format
  76. the contents of the notification when a new objects of subtype 'photo' is created:
  77. .. code-block:: php
  78. /**
  79. * Initialize the photos plugin
  80. */
  81. function photos_init() {
  82. elgg_register_notification_event('object', 'photo', array('create'));
  83. elgg_register_plugin_hook_handler('prepare', 'notification:create:object:photo', 'photos_prepare_notification');
  84. }
  85. /**
  86. * Prepare a notification message about a new photo
  87. *
  88. * @param string $hook Hook name
  89. * @param string $type Hook type
  90. * @param Elgg_Notifications_Notification $notification The notification to prepare
  91. * @param array $params Hook parameters
  92. * @return Elgg_Notifications_Notification
  93. */
  94. function photos_prepare_notification($hook, $type, $notification, $params) {
  95. $entity = $params['event']->getObject();
  96. $owner = $params['event']->getActor();
  97. $recipient = $params['recipient'];
  98. $language = $params['language'];
  99. $method = $params['method'];
  100. // Title for the notification
  101. $notification->subject = elgg_echo('photos:notify:subject', array($entity->title), $language);
  102. // Message body for the notification
  103. $notification->body = elgg_echo('photos:notify:body', array(
  104. $owner->name,
  105. $entity->title,
  106. $entity->getExcerpt(),
  107. $entity->getURL()
  108. ), $language);
  109. // Short summary about the notification
  110. $notification->summary = elgg_echo('photos:notify:summary', array($entity->title), $language);
  111. return $notification;
  112. }
  113. .. note::
  114. Make sure the notification will be in the correct language by passing
  115. the reciepient's language into the ``elgg_echo()`` function.
  116. Registering a new notification method
  117. ======================================
  118. By default Elgg has two notification methods: email and the bundled
  119. site_notifications plugin. You can register a new notification
  120. method with the `elgg_register_notification_method()`__ function.
  121. __ http://reference.elgg.org/notification_8php.html#ac9e7b5583afbb992b8222ae1db072dd1
  122. Example:
  123. --------
  124. Register a handler that will send the notifications via SMS.
  125. .. code-block:: php
  126. /**
  127. * Initialize the plugin
  128. */
  129. function sms_notifications_init () {
  130. elgg_register_notification_method('sms');
  131. }
  132. After registering the new method, it will appear to the notification
  133. settings page at ``www.example.com/notifications/personal/[username]``.
  134. Sending the notifications using your own method
  135. ===============================================
  136. Besides registering the notification method, you also need to register
  137. a handler that takes care of actually sending the SMS notifications.
  138. This happens with the ``'send', 'notification:[method]'`` hook.
  139. Example:
  140. --------
  141. .. code-block:: php
  142. /**
  143. * Initialize the plugin
  144. */
  145. function sms_notifications_init () {
  146. elgg_register_notification_method('sms');
  147. elgg_register_plugin_hook_handler('send', 'notification:sms', 'sms_notifications_send');
  148. }
  149. /**
  150. * Send an SMS notification
  151. *
  152. * @param string $hook Hook name
  153. * @param string $type Hook type
  154. * @param bool $result Has anyone sent a message yet?
  155. * @param array $params Hook parameters
  156. * @return bool
  157. * @access private
  158. */
  159. function sms_notifications_send($hook, $type, $result, $params) {
  160. /* @var Elgg_Notifications_Notification $message */
  161. $message = $params['notification'];
  162. $recipient = $message->getRecipient();
  163. if (!$recipient || !$recipient->mobile) {
  164. return false;
  165. }
  166. // (A pseudo SMS API class)
  167. $sms = new SmsApi();
  168. return $sms->send($recipient->mobile, $message->body);
  169. }
  170. Subscriptions
  171. =============
  172. In most cases Elgg core takes care of handling the subscriptions,
  173. so notification plugins don't usually have to alter them.
  174. Subscriptions can however be:
  175. - Added using the `elgg_add_subscription()`__ function
  176. - Removed using the `elgg_remove_subscription()`__ function
  177. __ http://reference.elgg.org/notification_8php.html#ab793c2e2a7027cfe3a1db3395f85917b
  178. __ http://reference.elgg.org/notification_8php.html#a619fcbadea86921f7a19fb09a6319de7
  179. It's possible to modify the recipients of a notification dynamically
  180. with the ``'get', 'subscriptions'`` hook.
  181. Example:
  182. --------
  183. .. code-block:: php
  184. /**
  185. * Initialize the plugin
  186. */
  187. function discussion_init() {
  188. elgg_register_plugin_hook_handler('get', 'subscriptions', 'discussion_get_subscriptions');
  189. }
  190. /**
  191. * Get subscriptions for group notifications
  192. *
  193. * @param string $hook 'get'
  194. * @param string $type 'subscriptions'
  195. * @param array $subscriptions Array containing subscriptions in the form
  196. * <user guid> => array('email', 'site', etc.)
  197. * @param array $params Hook parameters
  198. * @return array
  199. */
  200. function discussion_get_subscriptions($hook, $type, $subscriptions, $params) {
  201. $reply = $params['event']->getObject();
  202. if (!elgg_instanceof($reply, 'object', 'discussion_reply', 'ElggDiscussionReply')) {
  203. return $subscriptions;
  204. }
  205. $group_guid = $reply->getContainerEntity()->container_guid;
  206. $group_subscribers = elgg_get_subscriptions_for_container($group_guid);
  207. return ($subscriptions + $group_subscribers);
  208. }