Stream API v1

Revision as of 13:19, 1 February 2013 by Sinisakrisan (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

WARNING: API explained bellow works only with JomSocial 2.6 and below. If you need Activity Stream API for version 2.8 you need to implement a slight change which is explained , here

Activity stream represent a user action within the site. A user can follow his/her own or friends activity within the site. Activity stream will be visible in each user profile.
A user point system is calculated based on user activity.
However with the new UserPoints system introduced, now user point and activity are no longer tied to each other.
Each activity (new wall post, new blog entry, etc) can be assigned a point value through UserPoints API call.
Please refer to UserPoints System for more details on how points can be given to user.

Creating New Activity

Before you can create or register a new activity, you will need to understand some basic concept.

actor

  • Actor is the person who carry out the action

target

  • (Optional) A target is a user who's object is being manipulated by actor

title

  • The actual activity title

content

  • (optional) A longer description of the activity

apps

  • The application name that the activity run on

cid

  • (optional) any unique id, unique to the application.

Aggregated activities

Multiple activities can be aggregated into a single 'story'. For example

  • John added Twitter application
  • Jane added Twitter application
  • Joe added Twitter application

will be converted to

  • John, Jane and Joe add Twitter application

For the aggregator to work properly, the activities will need to be

  • from the same application (app)
  • with the same title
  • with the same cid (must not be null)
  • the title contain the '{multiple}' hint.

In the example above, all 3 entry have the same title, {actor} added Twitter application, same app code, (twitter) and same cid (20)

$act = new stdClass();
$act->cmd 	= 'wall.write';
$act->actor 	= $my->id;
$act->target 	= 0; // no target
$act->title 	= JText::_('{actor} write on {target} wall');
$act->content 	= '';
$act->app 	= 'wall';
$act->cid 	= 0;
 
CFactory::load('libraries', 'activities');
CActivityStream::add($act);


Formatting "title"

When writing a title, you would normally want to take advantage of JomSocial content replacement system instead of hard coding everything. You can use the following tag within the title

{actor}

replaced with the actor display name along with link to his/her profile page

{actors}

replaced with the links to a number of user's display name along with link to his/her profile page, in aggregated mode

{target}

replaced with the actor display name along with link to his/her profile page

Prepare for aggregated activities

You can prepare your title for aggregated activity by using {multiple}...{/multiple} and {single} ...{/single} tag.

{multiple}...{/multiple}

Text wrapped within this tag will be removed in a non-aggregated view

{single} ...{/single}

Text wrapped within this tag will be removed in aggregated view

{count}

Show the number of activities that have been aggregated together
$act = new stdClass();
$act->cmd 	= 'photos.upload';
$act->actor 	= $my->id;
$act->target 	= 0; // no target
$act->title 	= JText::_('{actor} upload {single}a photo{/single}{multiple}{count} photos{/multiple}');
$act->content 	= '';
$act->app 	= 'wall';
$act->cid 	= 0;
$act->params	= '';  
 
CFactory::load('libraries', 'activities');
CActivityStream::add($act);


The the user upload 1 photos, the activity stream will show as "User upload a photo". In an aggregated mode, it will show as "User upload 5 photos".

Adding support for LIKE and COMMENT in stream

To add support for like and comment, simply add additional data within your $act object. It will now look like this.

$act = new stdClass();
$act->cmd 	= 'photos.upload';
$act->actor 	= $my->id;
$act->target 	= 0; // no target
$act->title 	= JText::_('{actor} upload {single}a photo{/single}{multiple}{count} photos{/multiple}');
$act->content 	= '';
$act->app 	= 'wall';
$act->cid 	= 0;
$act->params	= '';  
 
CFactory::load('libraries', 'activities');
$act->comment_type  = $command;
$act->comment_id    = CActivities::COMMENT_SELF;
 
$act->like_type     = $command;
$act->like_id     = CActivities::LIKE_SELF;
 
CActivityStream::add($act);


The $command in this case is simply a short string that uniquely identify your particular stream type. If your plugin is called 'mypplugin', your comment_type and like_type can be called 'myplugin.myaction' .