Elgg
Contents |
Events happen all the time in an Elgg system, whether triggered by a user or the system. In many cases notifications will get sent to a user or users, and all this is being handled by the extensible notifications system which also allows plugins to register additional notification handlers in addition to the default email handler (for example, an SMS or IM message).
The generic method to send a user a message is via notify_user(). This function will in turn notify all registered handlers and will pass them the necessary parameters.
To register a notification handler, create a function for this which will need to get registered with register_notification_handler(). This function requires two parameters:
An array containing any configuration settings for the handler can be passed as an optional third parameter. Any array with values passed to notify_user() as an optional third parameter will get passed to the handler to process further.
A notification handler should accept the following parameters:
$from (guid)
$to (guid or array of guids)
$subject (string)
$message (string)
$params
$from will be an entity guid (so either a user, site, object or group) and $to will be the guid of a user or an array of users.
The notification handler will take into consideration any user preferences on how to deliver the message. There is one option however to override the user's preferred delivery methods by passing a fourth parameter, containing a string or array of strings containing the delivery methods to use.
If you like, you can allow users to be notified when any of their contacts create new content.
A notification function is triggered on all create events for entities; should the entity in question be of a type that's been registered for notifications, a message will be created and sent to users depending on their notification preferences and whether they're set up to receive notifications from that user. This requires a relationship called notify to be established between the subscriber user and the author.
To register an entity type for notifications, use the register_notification_object function, which takes these parameters:
$entity_type The type of entity (object, site etc)
$entity_subtype The subtype of entity (blog, etc)
$string A human-readable string representing the create action for this type of entity (eg "New blog post")
By default, the notification message (i.e., the message a user receives) will contain the string above and a link to the content. However, for some types of content you may wish to include a full representation of the text, or something else entirely. A plugin hook allows you to intercept.
Listen to the plugin hook notify:entity:message for your entity type. As part of the parameters, the entity will be passed as entity; the destination user as to_entity; the notification method as method. Your plugin hook function should return the notification message as a string. This will replace the default.