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.

This Toolbar API allows 3rd party plugin provider to add custom toolbar item in JomSocial toolbar menu. This API will be available in JomSocial version 1.2. The below article will show how developers can add new menu items into JomSocial toolbar through plugin.

Utilise onSystemStart in your plugin

The toolbar API will only work in any of your plugins through onSystemStart function. In JomSocial, every pages will first execute this onSystemStart trigger. Thus, calling this toolbar API in onSystemStart will ease the creation of custom toolbars into JomSocial.

function onSystemStart()
{
   include_once (JPATH_ROOT . DS . "components" . DS . "com_myblog" . DS . "functions.myblog.php");
   if(! class_exists('CFactory'))
   {
      require_once( JPATH_ROOT . DS . 'components' . DS . 'com_community' . DS . 'libraries' . DS . 'core.php');
   }
   //initialize the toolbar object  
   $toolbar =& CFactory::getToolbar();
   $userName     = $this->_user->getDisplayName();
   $myblogItemId = myGetItemId();
   //adding new 'tab' 'MyBlog' in JomSocial toolbar
   $toolbar->addGroup('MYBLOG', 'MyBlog', 
 JRoute::_('index.php?option=com_myblog&task=adminhome&Itemid='.$myblogItemId));
   if( myGetUserCanPost() )
   {
      $writeUrl  = 'myAzrulShowWindow(\''.JURI::root().'index.php?option=com_myblog'
                . '&tmpl=component&task=write&keepThis=true&TB_iframe=true&no_html=1&id=0\')';
      $toolbar->addItem('MYBLOG', 'MYBLOG_WRITE', 'Write Blog', $writeUrl, '', true);    
   }
   $toolbar->addItem('MYBLOG', 'MYBLOG_VIEW', 'View Your Blog', 
 JRoute::_('index.php?option=com_myblog&blogger='.$userName.'&Itemid='.$myblogItemId));
   $toolbar->addItem('MYBLOG', 'MYBLOG_ALL', 'All Blog Entries', 
  JRoute::_('index.php?option=com_myblog&Itemid='.$myblogItemId));
}

The above example will create a JomSocial's tab called 'MyBlog'.

Calling the CToolbar API

Before you can call the CToolbar API, you will need to make sure, JomSocial core class 'CFactory' is loaded. We will need this CFactory to load the CToolbar class object later on.

if(! class_exists('CFactory'))
{
   require_once( JPATH_ROOT . DS . 'components' . DS . 'com_community' . DS . 'libraries' . DS . 'core.php');
}

Here is how we can get the Ctoolbar object from CFactory.

$toolbar =& CFactory::getToolbar();

The first things that you will need to do is to add a toolbar 'group' if you wanted a new 'tab' in JomSocial toolbar menu. Here is the list of functions available in CToolbar library:

/**
 * Function to add new toolbar group.
 * param - key : string - the key of the group
 *       - caption : string - the label of the group name
 *       - link : string - the url that link to the page
 */
function addGroup($key, $caption='', $link=''){}
/**
 * Function used to remove toolbar group and its associated menu items.
 * param - key : string - the key of the group
 */
function removeGroup($key){}
/**
 * Function to add new toolbar menu items.
 * param - groupKey : string - the key of the group
 *       - itemKey : string - the unique key of the menu item 
 *       - caption : string - the label of the menu item name
 *       - link  : string - the url that link to the page
 *       - order : string - display sequence : append | prepend 
 *       - isScriptCall : boolean - to indicate whether this is a javascript function or is a anchor link.
 *       - hasSeparator : boolean - to indicate whether this item should use the class 'seperator' from JomSocial.      
 */
function addItem($groupKey, $itemKey, $caption='', $link='', $order='append', $isScriptCall=false, $hasSeparator=false){}
/**
 * Function used to remove toolbar menu item
 * param - groupKey : string - the key of the group
 *       - itemKey : string - the unique key of the menu item
 */
function removeItem($groupKey, $itemKey){}
/**
 * Function used to return html anchor link
 * param  - string - toolbar group key  
 *        - string - order of the items    
 * return - string - html anchor links  
 */    
function getMenuItems($groupKey, $order){}
/**
 * Function to retrieve those toolbar that user custom add.
 *  return - an array of objects.  
 */  
function getExtraToolbars(){}
/**
 * Function to retrieve custom toolbar menu items to caller
 * param - groupKey : string - the key of the group 
 * return array of object
 */
function getToolbarItems($groupKey){}
/**
 * Function used to determined whether a core menu group was set.
 * param  - string - toolbar group key
 * return - boolean  
 */      
function hasToolBarGroup($groupKey){}
/**
 * Function to get the current viewing page, the toolbar group key.
 * param  - string - uri of the current view page      
 * return - string   
 */
function getActiveToolBarGroup($uri){}
/**
 * Function used to return all the toolbar group keys.     
 * return - array  
 */  
function getToolBarGroupKey(){}
/**
 * Function to get the toolbar group key based on what view being associated.
 * param  - string - view name     
 * return - string
 */ 
function getGroupActiveView($viewName){}
/**
 * Function to add views that associated with the toolbar group.
 * param  - string - group key
 * param  - string - view name
 */
function addGroupActiveView($groupkey, $viewName){}

Adding new 'toolbar' and toolbar's menu items

Below statement is how we can add new toolbar, or, preferable 'tab', into jomsocial.

$toolbar->addGroup('MYBLOG', 'MyBlog', JRoute::_('index.php?option=com_myblog&task=adminhome&Itemid='.$myblogItemId));

Here is the function defination of addGroup:

function addGroup($key, $caption='', $link=''){}
$key     - The unique key used.
$caption - The label caption of your tab.
$link    - The url link.

If your menu link is point to outside of JomSocial, you should use JRoute::_() instead of CRoute::_(). Also, you must add the group follow by the group's items otherwise all your item will not be shown in JomSocial toolbar menu.

$toolbar->addItem('MYBLOG', 'MYBLOG_VIEW', 'View Your Blog', 
 JRoute::_('index.php?option=com_myblog&blogger='.$userName.'&Itemid='.$myblogItemId), 'prepend');
$toolbar->addItem('MYBLOG', 'MYBLOG_ALL', 'All Blog Entries', 
 JRoute::_('index.php?option=com_myblog&Itemid='.$myblogItemId), 'append');

Above is how you add menu items into your own toolbar tab. addItem works almost the same as addGroup but with few extra parameters with the following order.

function addItem($groupKey, $itemKey, $caption='', $link='', $order='append', $isScriptCall=false, $hasSeparator=false){}
$groupKey     - The key used in your custom toolbar menu. In this case is the 'MYBLOG'
$itemKey      - The unique key used in your menu items.
$caption      - The label caption of the menu item.
$link         - The url link.
$order        - The order of the menu item. Possible value ( 'prepend','append' ). Default is 'append'
$isScriptCall - To indicate whether this is a javascript function or is a anchor link.
$hasSeparator - To indicate whether this item should use the class 'seperator' from JomSocial.

Below is the example on how you can call a javascript function from the link.

$writeUrl  = 'myAzrulShowWindow(\''.JURI::root().'index.php?option=com_myblog'
                . '&tmpl=component&task=write&keepThis=true&TB_iframe=true&no_html=1&id=0\')';
$toolbar->addItem('MYBLOG', 'MYBLOG_WRITE', 'Write Blog', $writeUrl, '', true);

Above is the example of JomSocial custom toolbar menu 'MyBlog'.

Add extra menu into exisiting JomSocial toolbar

In some circumstances, we need to add extra menu items into JomSocial existing toolbar menu. CToolbar allow you to achieve that. Below is the existing constant / predefined toolbars that are available by default.

TOOLBAR_HOME - Home toolbar
TOOLBAR_PROFILE - Profile toolbar
TOOLBAR_FRIEND  - Friend toolbar
TOOLBAR_APP     - Application toolbar
TOOLBAR_INBOX   - Inbox toolbar

The example below will demonstrate how you add 'Logout' menu item into 'Home' toolbar.

function onSystemStart()
{
   if(! class_exists('CFactory'))
   {
      require_once( JPATH_ROOT . DS . 'components' . DS . 'com_community' . DS . 'libraries' . DS . 'core.php');
   }
   //initialize the toolbar object  
   $toolbar =& CFactory::getToolbar();
   $toolbar->addItem(TOOLBAR_HOME, 'HOME_LOGOUT', 'Logout', CRoute::_('index.php?option=com_user&view=login'));
}

Calling the same method addItem, you now added the 'Logout' menu item.

Removing core menu group or core menu items from JomSocial toolbar.

Ctoolbar library actually allow you to remove any core menu items or even removing the core menu group completely from showing. To remove a core menu group from JomSocial toolbar, we use function removeGroup().

$toolbar->removeGroup(TOOLBAR_INBOX);

If you just want to remove one or some of the core menu items, then you should use this function removeItem() instead. By giving the correct menu group key and menu item key, you can remove any of the core menu items from JomSocial.

$toolbar->removeItem(TOOLBAR_INBOX, 'INBOX_INBOX');

Here is the key string that used in JomSocial toolbar menu items.

Profile
 
'PROFILE_AVATAR'       - Change profile picture
'PROFILE_EDIT_PROFILE' - Edit Profile  
'PROFILE_EDIT_DETAILS' - Edit Details
'PROFILE_EDIT_PRIVACY' - Privacy

Friends
 
'FRIEND_SHOW_ALL_FRIENDS'       - Show all
'FRIEND_SEARCH_FRIENDS'         - Search
'FRIEND_ADVANCE_SEARCH_FRIENDS' - Advanced Search
'FRIEND_INVITE_FRIENDS'         - Invite Friends
'FRIEND_REQUEST_SENT'           - Request sent
'FRIEND_PENDING_APPROVAL'       - Pending my approval

Application
 
'APP_EDIT_APPS'   - My Applications
'APP_BROWSE_APPS' - Browse
'APP_GROUP'       - Groups
'APP_PHOTOS'      - Photos
'APP_VIDEOS'      - Videos

Inbox
 
'INBOX_INBOX'  - Inbox
'INBOX_SENT'   - Sent
'INBOX_WRITE'  - Write

Reporting allows 3rd party application / module provider to generate a link that will allow guests / members to report against an item. The item here could refer to any object within the page. There is 3 main steps that needs to be done to achieve this,

Generate HTML codes

Generate the 'HTML' codes and display it within your application / module.

// Load libraries
CFactory::load('libraries', 'reporting');
$report   = new CReportingLibrary();
$html   = $report->getReportingHTML( JText::_('CC REPORT BAD USER') , 'profile,reportProfile' , array( $user->id ) );

JText::_('CC REPORT BAD USER') - The first parameter here informs the library to display this text in the html codes.
profile,reportProfile - Second parameter informs the library to call the method to register your tasks. To register a call for plugins, you can use plugins,pluginname,method.
array( $user->id ) - Third parameter is the unique id that you are reporting against.

Registering the report action

/**
 * Method is called from the reporting library. Function calls should be
 * registered here.
 *
 * return  String  Message that will be displayed to user upon submission.
 **/
function reportProfile( $link, $message , $id )
{
 CFactory::load( 'libraries' , 'reporting' );
  $report = new CReportingLibrary();
 $report->createReport( JText::_('Bad user') , $link , $message );
  $action         = new stdClass();
 $action->label     = 'Block User';
 $action->method      = 'profile,blockProfile';
 $action->parameters    = $id;
  $action->defaultAction = false;
 $report->addActions( array( $action ) );
  return JText::_('CC REPORT SUBMITTED');
}

For plugins, simply create the function in your plugin and the system will automatically call this method.
$action->method - To register a call for plugins, you can use plugins,pluginname,method .

Creating method that will be executed by the administrator

When the report item is added to the system, the administrator will then be able to perform the actions based on what you have parsed to the system. For an example, the 'block profile' method below, will block the user when the administrator clicks on the link.

/**
 * Function that is called from the back end
 **/    
function blockProfile( $userId )
{
 $user   =& CFactory::getUser( $userId );
  $user->set( 'block' , 1 );
 $user->save();
 return JText::_('CC USER ACCOUNT BLOCKED');
}

The return value will be a normal string output which will be displayed to the administrator.

For plugins, simply create the function in your plugin and the system will automatically call this method.

Background on Wall features

Walls / comments is simply a commenting system in Jom Social. It allows comments to be placed on 3rd party applications within the system just like the walls /comments you see on the core applications. Before even beginning writing the codes to integrate the walls / comments into your 3rd party application, you should by now fairly understand how Jom Social works and you should by now have at least a little knowledge on the Joomla!™ MVC framework.

Including necessary libraries

The first step, is to include the necessary library so that your application can start using them.

require_once( JPATH_COMPONENT . DS . 'libraries' . DS . 'wall.php' );

Usage

After including the necessary files, all you have to do now is to get the form for the walls /comments and the contents of the walls / comments.

Getting the forms

To get the form's HTML content, you simply need to issue the following block of codes. The parameters are explained below,

$form = CWallLibrary::getWall( $uniqueID , $applicationName );

$uniqueID : This parameter is required and it tells the wall system that a wall / comment is made on this specific unique id.

$applicationName : This parameter is required and it tells the wall system to call your AJAX methods within your class. It should always have the prefix of 'plugins,' followed by your application name. E.g:

This example, selects the unique id for the specific image that is being commented on.

$db    =& JFactory::getDBO();
$query = 'SELECT `id` FROM ' . $db->nameQuote('#__myapplication_images');
$db->setQuery( $query );
$uniqueID = $db->loadResult();
if($db->getErrorNum())
{
 JError::raiseError( 500, $db->stderr());
}

A JomSocial plugin allows developer to extends JS and provide new functionality easily. A plugin is essentially a normal Joomla! plugin that can be installed, uninstall and manage just like a normal Joomla! plugin.

JomSocial provide a few system hooks, or trigger point which your plugin will override to add new functionality to JomSocial

A plugin can either be

system plugin
profile plugin

System Plugin

System plugin allows you to perform various system wide task.

Profile Plugin

When you create a profile plugin, a site members will be able to select your plugin to be displayed in their profile page. Your plugin will be able to draw on user profile page and will have access to user various parameters.

Tutorials

Creating a JomSocial plugin is easy. At least, you will need 2 file, the plugin php file and its xml file.

Sample of system plugin

example.php

In your main php file, you will need to

include JomSocial core file
declare a class with plgCommunity[Plugin name] format. This class should extends CApplications class.

defined('_JEXEC') or die('Restricted access');
require_once( JPATH_ROOT.DS.'components'.DS.'com_community'.DS.'libraries'.DS.'core.php');
class plgCommunityExample extends CApplications
{
  var $name = 'Invite';
 var $_name  = 'invite';
  function plgCommunityExampl(& $subject, $config)
  {
   parent::__construct($subject, $config);
 }
}

example.xml

Please take note that there is a few additional element

isapplication: If set to true, the application can be selected by user from the front-end
Param coreapp: Within the params section, please add a param named 'coreapp'. This allow admin to force this application to appear on all user profile.

Accessing parameter

There are 2 types of plugin parameters, the site plugin params and user params

Default system parameters

System parameters are setting that are specified by the server administrator. It cannot be changed by the user and admin can only modify the setting from Joomla backend.

This params is loaded automatically and can be accessed right away.

$db_name = $this->params->get('db_name', '');

User parameters

A user parameter is params data specific to the current user. To define this params, create a file called config.xml inside the plugin folder.

To use any user specific parameter, you will need to load it before you can use it. Just call

$this->loadUserParams();
// After loading, userparams object (JParameters) will be available to yoi
$path = $this->userparams->get('path', '');

Caching plugin content

JomSocial, by default does not cache the return values for plugins. If any plugin want to use any caching system, you can deploy standard Joomla caching system.

Example

class plgCommunityTwitter extends CApplications
{
 var $name     = "Me on twitter";
  var $_name    = 'twitter';  
 function onProfileDisplay()
 {
   $config =& CFactory::getConfig();
   $this->loadUserParams();
    $uri    = JURI::base();
   $my   =& JFactory::getUser();
   $user   =& CFactory::getActiveProfile();
    $document =& JFactory::getDocument();
   $css    = $uri  .'plugins/community/groups/style.css';
    $document->addStyleSheet($css);  
   $username = $this->params->get('username');
   $password = $this->params->get('password');
    $cache =& JFactory::getCache('community');
    $callback = array($this, '_getTwitterHTML');
   $content = $cache->call($callback, $username, $password, 
      $this->params, 
      $user, $my);
   return $content; 
 }
  function _getTwitterHTML($username, $password, &$params, &$user, &$my) {
    /* Do the processing here */
    return $content;
  }

Note

Get the cache object with 'community' community.
The function that return the final content should not try to get the 'user' and 'my' object. Caller should instead pass these data to the function.
Any css/js attachment should be attached outside the cached function.