Notifications & Emails (*) > - IP.Board (IPB) News
Kanał Rss Kanał Rss
Kanał Atom Kanał Atom

Notifications & Emails (*)

wersja drukowalna wersja Microsoft Word wersja HTML

You have a number of options available for you for sending notifications to members:

Though all 3 systems interact with each other, it is important not to confuse them: the follow system sends a notification which may be an email. You can also send a notification which may be an email, or you can just send an email.

If you need to send a notification to a user, you should think carefully about whether a notification or an email is appropriate. Generally notifications are best for telling a user about something that has happened that they might be interested in (for example, notifications are sent when someone posts on another user's profile) and emails are best for things which are in response to a specific action, or require action from the user (for example, an email is sent when a product a user has purchased from Commerce is shipped).



Step 1: Create an extension

In the Developer Center for your application go to Extensions > core and click the "+" button on the "Notifications" row. A file will be created in your application's extensions/core/Notifications folder with a skeleton to get you started. Open that file and follow the instructions within it to add your notification types to the Notification Options screen and create the method(s) which will control what gets displayed when the user clicks on the notification icon in the header.

Step 2: Create email templates

You must create the email templates for what will get sent to users who have opted to receive emails for your notification. Follow the instructions from Steps 1-2 of the Emails instructions below. For your templates, use notification_key as the key (where key is the notification key you specify in getConfiguration()). For example: the notification type new_status (in the core application) uses the email templates notification_new_status which for it's subject uses the language string mailsub__core_notification_new_status.

Step 3: Send the notification

The actual code to send the notification is very simple:

$notification = new IPSNotification( IPSApplication::load('app'), 'key', $item, $params );
$notification->recipients->attach( IPSMember::load(1) );

$item should be an object of the thing the notification is about, which is used to prevent the same notification being sent more than once or NULL if not applicable. If it is a content item (it doesn't have to be, but if it is) the notification will automatically remove the recipient if they don't have permission to read the item or are ignoring the user who posted it.

$params can be any parameters that you want to pass to the email template.

You call $notification->recipients->attach() for each member you want to send the notification to, passing an IPSMember object.



Step 1: Create the templates

The content for emails is stored in the dev/email folder of the application which will send the email. For example, if you look in the applications/core/dev/email folder (you will need to be in developer mode to see that folder) you will see all the emails the core application sends.

All emails sent from the IPS Community Suite are sent in two formats: HTML (for most email clients) and plain text (for older email clients or users who specifically do not want to see HTML emails). For each type of email that can be sent, there are two files: key.phtml (which contains the HTML version) and key.txt (which contains the plaintext version).

To send your own type of email, you will need to create both of these. They key you use can be anything so long as it is unique. The first line of both files should be a tag like this:

<ips:template parameters="$parameter1, $parameter2, $email" />

Later (in step 3) when you call the code to send your email you can pass whatever parameters you want which can then be used in your templates. A final parameter, $email, will also always be passed which contains the IPSEmail object you're working with.

Within the templates, you can include template logic and most template tags, however be careful: the email you're sending will probably be to a different user to who is logged in when the email is sent, so do not use anything which is dependant on the currently logged in member. most importantly, do not use {lang=""} template tag (which is always based on the currently logged in member). Instead, you can access $email->language which is an IPSLang object for the correct language of the recipient.

When creating your HTML template, be aware that email clients use very different standards to browsers and many normal techniques cannot be used. We recommend you use a template from one of the IPS applications as your base.

When creating your plaintext template, be aware that you cannot use any HTML tags, and whitespace is displayed.


Step 2: Subject language string

The system will automatically look for a language string with the key mailsub__app_key to use as the subject, so add that to your dev/lang.php file. Note that you can use the parameters you pass to the template - for example, you will notice in applications/core/dev/lang.php:

'mailsub__core_notification_new_likes'	=> '{$member->name|raw} liked your post',	


Step 3: Send the email

The actual code to send the email is very simple:

IPSEmail::buildFromTemplate( 'app', 'key', $params )->send( $member );

The send() method can be passed either an IPSMember object (this is best as the system will automatically customise for the user, including choosing the correct language) or an email address as a string (which you should only do if you need to send an email to unregistered users) or an array of either of these to send to multiple recipients. You can also pass second and third parameters for user's to CC and BCC respectively. 

If you want to customise the content of the message depending on the member you can include variables in your template with the format *|key|* and then send like so:

IPSEmail::buildFromTemplate( 'app', 'key', $params, TRUE )->mergeAndSend( array(
    '' => array(
        'key'   => 'value for user 1',
    '' => array(
        'key'   => 'value for user 2',
) );


Testing Script

For an easy way to see the content for your email templates, use the attached script. First open it to specify your application key and what parameters to use and then run it from your community's root directory:


czw, 01 wrzesień 2016