Difference between revisions of "Stream API v2"

Revision as of 12:43, 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 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 a activity stream item title. Since 2.8 we are using it as attachment title. 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 the name of activity stream template you will use for the activity. Yes, JomSocial now allows you to use different templates too, but in most cases, you will want to use the action template