Difference between revisions of "Notifications API"

Revision as of 15:37, 1 October 2013

Overview

The built in notification system, first ever in Joomla, allows your app to keep the user (or group of users) informed about various different events. Think of notifications as important alerts that user would be interested to read and keep track of it.
Notifications can be generated everywhere. In your component or plugins and later displayed inside JomSocial notification system.
This tutorial will show you how, but since we do not have idea of any third-party component we could use :) the examples will be done on a community plugin which will be triggered at onAfterProfileUpdate event
If you don't know how to create plugin which will be triggered on this event, we suggest you to check this guide

Implementing it in your component anyway

As stated in overview of this tutorial, we will generate notifications using community plugin.
You will most likely want to create notifications inside your component, or your plugin. The following tutorial will work fin any of this cases. You only need to determine at what point in your code the notification will be created and just load the JomSocial Core Libraries file.

require_once JPATH_ROOT .'/components/com_community/libraries/core.php';

Following the tutorial explained bellow will work just fine for your extension too

Preparing the Development Environment

1. We will assume that you're already created community type example plugin which will be triggered when user changes its profile
If not, you can download empty example plugin from this link, install it in Joomla and enable the plugin. It is named Community - Notifications Example
2. Navigate to your database and empty these two tables, so they dont have any records at all

a) prefix_community_notification

b) prefix_community_mailq

3. Have at least two (2) users at your test sites and know their ID's

In earlier versions of Joomla, user ID's have always started from specified number (62, 42) In Joomla 3, this number will be random, hence, the picture of our testing environment because it will definitely be different at your end.

The First Notification

Open the plugin php file which will be located in ROOT/plugins/community/example
Within the function onAfterProfileUpdate() replace the

// do the magic here

with

CNotificationLibrary::add( $cmd , $actor , $target , $subject , $body , $template , $params );

As shown on the example, notification add api have 7 parameters

1. $cmd - is the notification type. You can see all notifications types in this file. ROOT/components/com_community/libraries/notificationtypes.php starting from, or around line 53. We recommend using system_messaging notification type.
2. $actor - is the person who carry out the action
3. $target - is the person, or group of people that will receive notification
4. $subject - is the notification subject, in both, notification popup window and the email title
5. $body - is the body of email notification message
6. $template - if you need specific template to use, you can define it here. Otherwise, this parameter can be empty
7. $params - custom defined parameters

Knowing all this, lets define the variables we will use
Change your plugin code to:

$user = CFactory::getUser();
$cmd = 'system_messaging'; // first param, type of activity
$actor = $user->id; //second param - get the id of $actor
$target = '965'; // third param. Who receive notification? In our dev environment, its admin user with id 965. At your environment, you will most likely want to get the ID from your object or from array of users.
$subject = 'Notification Subject'; // Subject of both, email and popup notifications
$body = 'This is the notification body message'; //Body message in emails.
$template = ''; // If you need to use specific jomsocial template file, you can define it here.
$params = new CParameter(''); // We want to create an additional params object, and assign data to it, without having to formally define a class
CNotificationLibrary::add( $cmd , $actor , $target , $subject , $body , $template , $params );

Now login with any user and change the profile information. Lets go to database to see what happened.
Navigate to prefix_community_notifications table and observe the new record

Navigate to prefix_community_mailq table, and see the new record