Difference between revisions of "Stream API v2"

Revision as of 17:35, 24 April 2013

Overview

Since JomSocial 2.8 onwards, we bring the massive change in how activity streams are handled and introduce a set of new rules to follow which will allow more freedom for third party developers to easier customize every individual's activity stream item;
JomSocial 2.8+ streams are NOT backward compatible with JomSocial 2.6 and bellow, however, some legacy support for old activity stream exist in JomSocial 2.8 and above. This does not necessarily mean your old activity will work though.
You can still use the old API to create the activity streams, but you can't use the {multiple}...{/multiple} tags anymore as they are completely removed and will cause activity streams to break. (It will be created, but will not be shown on Front End).

Storing & Displaying

Unlike JomSocial 2.6 and bellow, where third party activity streams were created by JomSocial APIv1 and later displayed "as they are" directly from the database, in Stream API v2 we first store the activity stream in the database and then manipulate the database data with the community-type plugin

Storing

Storing the data is pretty much straight forward task and is exactly the same as in V1 with use of CActivityStream::add API
We will provide just a basic example here

$act            = new stdClass();
$act->cmd 	= 'example.task';
$act->actor 	= $my->id;
$act->target 	= 0;
$act->title 	= 'string';
$act->content 	= 'Your activity content';
 
// Pay close attention on this
$act->app 	= 'example.action';
//$act->favicon   = '';
 
CActivityStream::add($act);

Lets decompose this very basic activity stream item addition

• $act = new stdClass(); - We want to create an activity stream object, and assign data to it, without having to formally define a class.
• $act->cmd = 'example.task'; - An unique custom command for your activity used for likes and comments. You can set this to any value but the best practice is to name it like pluginname.task
  • pluginname will be explained later. It will be the name of plugin we will create through this turorial
  • task is simply a command that will help you to easier distinguesh the different activities. For example, if you want to integrate the forum component, you can replace the word task with newpost or newthread but whitespace is not allowed
• $act->actor = $my->id; - Actor is the person who carry out the action
• $act->target = 0; - (Optional) A target is a user who's object is being manipulated by actor. Leave it to 0 if your activity wont have the target
• $act->title = 'string'; - Since 2.8 title have different purpose. In 2.6 and bellow, title was used as an activity stream item title. Since 2.8 we are using it as an title above attachment. We will come to attachments later in this article.
• $act->content = 'Your activity content'; - This will be the activity content
• $act->app = 'example.action'; - This is the most important part of the API. You are absolutely required to define the app name exactly as your plugin will be named, which in this tutorial is example
  • example - is the name of the plugin we are about to create
  • action - is simply a name of the carried action within the plugin
• CActivityStream::add($act); - And finally, this will store the activity stream object.

If you're already familiar with old API V1 you will notice that we only store the activity stream item. We do not want to think about implementing Likes and Comments anymore. Those are implemented by default now.

Displaying

This is where all the fun with activity stream items begin, but as stated earlier, you will need to create the community plugin.
If you dont know how to create a community plugin yet, please follow this guide
Before you start creating your plugin, ensure that your component properly store the activity stream into database. For this tutorial, i have added one row manually, but you will really want to check if your component adds it automatically.

As shown in the image above, this row doesn't really have any data, except the actor id and app name which for the very basic activity stream item is enough.
Through this documentation article, we will extend the activity item massively, but lets start creating our first activity stream plugin.
Exactly as required for creating community plugin we will first declare a class with the format, plgCommunity[Plugin name] which will extend CApplications class.
Within the plugin, we will now use onCommunityStreamRender() event which is available from JomSocial 2.8 onwards

class plgCommunityExample extends CApplications
{
	public function onCommunityStreamRender($act)
	{
    	$user = CFactory::getUser($act->actor);
 
    	$stream    = new stdClass();
    	$stream->actor  = $user;
    	$stream->headline = 'Headline';
    	$stream->message = 'Message';
    	return $stream;
	}
}

As you can see, we now have a very basic activity stream plugin which will display all activities created by $act->app = example.action app
When plugin is enabled, the stream will be shown like this

If you disable the plugin now, the content of it will disappear

Modifying Activity Stream Item

Examples above described how to get going with the very basic activity stream plugin. We now want to extend the functionality of the plugin and add the username to it as well as changing the headline
We will modify our code to look like this

class plgCommunityExample extends CApplications
{
	public function onCommunityStreamRender($act)
	{
    	JPlugin::loadLanguage ( 'plg_example', JPATH_ADMINISTRATOR ); // only use if theres any language file
    	$user = CFactory::getUser($act->actor);
    	$actorLink = '<a class="cStream-Author" href="' .CUrlHelper::userLink($user->id).'">'.$user->getDisplayName().'</a>';
 
    	$stream    = new stdClass();
    	$stream->actor  = $user;
    	$stream->headline = JText::sprintf('PLG_EXAMPLE_ACTIVITY_HEADLINE', $actorLink );
    	$stream->message = 'Message';
 
    	return $stream;
	}
}