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)
Example 1
$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
Example 2
$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. In example 2, 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' .
Advance newsfeed formatting
The newsfeed system also support developer assigned replacement rule.
WIP
User Points System
JomSocial user point system allows any 3rd party developer or application to easily rewards "points" to any user action. The points system does not require an activity stream item to be created and can be awarded at any event, deemed necessary.
The site admin will have the ability to modify the exact number of point to be awarded for each action and can also completely disable it if needed.
Calling the UserPoints API in your code.
If you want to give points to user, you will need to call the API to do that by inserting the codes to where you want.
include_once( JPATH_BASE . DS . 'components' . DS . 'com_community' . DS . 'libraries' . DS . 'userpoints.php');
CuserPoints::assignPoint('your.action.string');
The 'your.action.string' is the rule registered in db with how many points awarded to the current logged on user.
You will need to give a unique action string to your components such as 'com_name.profile.upload.avatar'.
In some situation, where you want to give points to other user instead of the current logged on user, you can call the API in this way :
include_once( JPATH_BASE . DS . 'components' . DS . 'com_community' . DS . 'libraries' . DS . 'userpoints.php');
CuserPoints::assignPoint('your.action.string', 62);
By giving the userId as the second parameter, the API will give points to the specified user.
Register action rules into database
To register all the action rules that used in your component / module / plugins, you will need to create an xml file for this.
Create one xml file and named it 'jomsocial_rule.xml'. You MUST named your file exactly or else the rule registration will failed.
You MUST include this file in your installer and put this file at root level in your front-end component folder.
Your xml file should look like the below one :
<version="1.0" encoding="utf-8"?>
<your component name>
<your action name>
<your description about the action>
<your unique action string.>
<whether to publish the rule or not. true or false>
<points given to this action.>
<user access level. For registered user, use 1.>
For example,
<version="1.0" encoding="utf-8"?>
<com_community>
<Add Application>
<Give points when registered user add new application.>
<com_community.application.add>
<true>
<1>
<1>
<Remove Application>
<Deduct points when registered user remove application.>
<com_community.application.remove>
<true>
<0>
<1>
For the access_level, these are the value you should use.
- 0 => Public
- 1 => Registered
- 2 => Special
Assuming you have included this ' jomsocial_rule.xml' into your installer.
Install your component through JOOMLA backend and your component folder 'com_xxx' should created in 'JOOMLA\components\com_xxx' and this xml should stay in 'JOOMLA\components\com_xxx\ jomsocial_rule.xml'.
Now go to your Jomsocial backend and you should see the icon 'UserPoints'.
Go into UserPoints and you should see screen below with some default / existing action rule displayed.
Click on the icon 'Rule Scan' to bring your to a popup screen.
This 'Rule Scan' will actually scan through all the components folder to search for the file 'jomsocial_rule.xml'.
If there are new rules, the scanning will register them into DB and you should see screen below for what rules registered.
Click on 'refresh' button to continue.
Thats it. Now all your action has been registered into db and your components should give points accordingly to where you have placed your UserPoints API.
You can always configure the action rule from JomSocial backend in UserPoints page. Below screen is where you can modify your rule's attributes.
