Collections functions
General functions
Render functions
Theme permission functions
Resource functions

Sending User Notifications

When sending a user notification the following settings should checked:-

  • Has the user chosen to receive these types of notifications?
  • Has the user chosen to receive emails instead of system messages?
  • Has the user chosen to receive emails in addition to system messages?
  • What language preference does the user have?

Before version 10 these checks had to be made before calling send_mail() or message_add() whenever required, resulting in duplicated code and inconsistency. From version 10 the new send_user_notification() function should be used instead.

Notification message structure

It is important to understand that for any language strings in the notification subject and text to be correctly translated when sending, these strings must not be added to the notification by referencing the $lang array as usual but should instead be built up using component parts as described below.

To send a notification the following steps need to be taken:-

  1. Create a new ResourceSpaceUserNotification instance
  2. Set the notification subject (required to send email)
  3. Set the main notification text
  4. Set the related notification URL e.g. link to a resource request
  5. Check a user preference that must be set if notification is to be sent (optional)
  6. Set the email template to use (optional)
  7. Set email template variables (optional)
  8. Set the associated event data. Used for system messages so that messages linked to e.g. user account requests get deleted when approved by another user (optional)
  9. Send the notification

Create the notification object

// Create a new instance of a ResourceSpaceUserNotification object
$approvemessage= new ResourceSpaceUserNotification;

Set the subject

For simple subject text the set_subject() function can be used

// Set the subject to be the application name  followed by a colon, e.g. 'Acme Image Library:'
$approvemessage->set_subject($applicationname . ": ");

Append text to the subject

// The next line will append the string "Fullname: %fullname%, email: %email%" to the subject, replacing the "%fullname%"" and "%email%" placeholders with the values of the variables $fullname and $email respectively
$approvemessage->append_subject("Fullname: %fullname%, email: %email%",["%fullname%","%email%"],[$fullname,$email]);

Set the main text of the message

The set_text() function will usually be used in conjunction with append_text()

// Set the text to be the language string 'requestassignedtouser', replacing the '%' placeholder with the relevant user's fullname and email in brackets
$approvemessage->set_text("lang_requestassignedtouser",["%"],[$assigned_to_user["fullname"] . " (" . $assigned_to_user["email"] . ")" ]);

Append text to the main body of the message

// Append the value of $nodevalue variable, translated according to the i18n syntax
$approvemessage->append_text("i18n_" . $nodevalue);

Get the text from a ResourceSpaceUserNotification object.

This can be either in raw form (for use in another ResourceSpaceUserNotification object), or with all strings resolved, placeholders replaced and concatenated for the current user (i.e. the 'final' version). Retrieving the text elements in raw form means that a notification instance can be used to hold a reusable section of text

// Get the text of the $coremessage object, with all strings resolved and concatenated
$coremessage->get_text();

// Get the text of the $coremessage object in raw form, to use in another instance
$coremessage->get_text(true);

Append multiple text elements to the main body of the message

This can be used in combination with get_text() to add the text elements from another instance of a ResourceSpaceUserNotification object.

// Append the text from the $coremessage instance
$approvemessage->append_text_multi($coremessage->get_text(true));

Prepend text string to the main body text

To prepend a text string to the ResourceSpaceUserNotification body text the prepend_text() function can be used

// Prepend the string defined by $lang["email"] to the message body
$approvemessage->prepend_text("lang_email");

Prepend multiple text elements to the main body of the message

This can be used in combination with get_text() to add the text elements from another instance of a ResourceSpaceUserNotification object.

$introtext[] = ["lang_user_made_request"];
$introtext[] = ["<br/><br/>"];
$introtext[] = ["lang_username"];
$introtext[] = [": "];
$introtext[] = [$username];
$notification_message->prepend_text_multi($introtext);

Sets the URL to be included in the message

// Add a link to the collection defined by the value of the $collection variable
$approvemessage->url = $baseurl . "/?c=" . $collection;

Optionally set a user preference that will be checked before sending the message

// Only send the notification if the user has the preference user_pref_resource_access_notifications ('Send me messages about resource access e.g. resource requests') set to true
$approvemessage->user_preference = "user_pref_resource_access_notifications";

Sets the email template to be used by the message

// Set the email to use the 'emailresearchrequestcomplete' template
$approvemessage->template = "emailresearchrequestcomplete";

Sets the email template variables to be used by the message

$templatevars["message"]      = $declinemessage->get_text();
$templatevars["url"]          = $baseurl . "/?c=" . $currentrequest["collection"];
$approvemessage->templatevars = $templatevars;

Optionally link the system message to a specific activity

The system message can be linked to a specific resource or account request so that it will be automatically deleted once the request has been processed. The array should have at least two elements, the type (e.g. MANAGED_REQUEST - see definitions.php) and the associated reference

// Set the message to be linked to a user account request for the auto created user account with the reference assigned to the $newuser variable
$approvemessage->eventdata = ["type"=>USER_REQUEST, "ref"=>$newuser];

Sending the notification

To send the notification call send_user_notification() with the following parameters

  1. An array of user IDs to send the notification to
  2. The ResourceSpaceUserNotification instance
  3. Force sending of an email instead of a system message (false by default)
// Send the $approvemessage to all system admins
$admin_notify_users=get_notification_users("SYSTEM_ADMIN");
send_user_notification($admin_notify_users,$approvemessage);