ApnaCafe 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.

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

A plugin can either be

1. system plugin
2. 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 ApnaCafe 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 ApnaCafe core file
• declare a class with plgCommunity[Plugin name] format. This class should extends CApplications class.

<?php
 
defined('_JEXEC') or die('Restricted access');
require_once( JPATH_BASE.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

<?xml version="1.0" encoding="utf-8"?>
<install version="1.5" type="plugin" group="community">
  <name>Walls</name>
  <author>apnacafe</author>
  <creationDate>7 October 2008</creationDate>
  <copyright>Copyright (C) 2008. All rights reserved.</copyright>
  <license>http://www.apnacafe.com</license>
  <authorEmail>
  This e-mail address is being protected from spambots. You need JavaScript enabled to view it
 </authorEmail>
  <authorUrl>www.apnacafe.com</authorUrl>
  <version>1.0</version>
  <isapplication>true</isapplication>
  <description>
    Example for ApnaCafe © apnacafe 2009
  </description>
  <files>
    <file plugin="example">example.php</file>
    <file>example.xml</file>
  </files>
 
  <params>
    <param name="cache" type="list" default="0" label="Enable caching" description="Cache data">
      <option value="0">No</option>
      <option value="1">Yes</option>
    </param>
    <param name="coreapp" type="list" default="0" label="Core Application" 
description="Causes this application to not appearin the users applications list but it will allow this application 
to appear in the user profile automatically if selected.">
      <option value="0">No</option>
      <option value="1">Yes</option>
    </param>
  </params>
</install>

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 paramaters 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.

Sample config.xml

<?xml version="1.0" encoding="utf-8"?>
<install version="1.5" type="plugin" group="community">
  <params>
    <param name="path" type="text" default="" label="Feed url"/>
    <param name="count" type="text" default="5" label="Count"  />    
  </params>
</install>

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

ApnaCafe, 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.

ApnaCafe Plugins Methods

Our aim is to keep ApnaCafe event trigger minimal, but complete. By keeping the event hooks low, we can ensure optimum performance of ApnaCafe. If, you need any additional event hooks, please send a request to This e-mail address is being protected from spambots. You need JavaScript enabled to view it and we will discuss about it and see if the additional event would be useful.

System Events

onSystemStart

Called before any controller is called

onSystemEnd

Called after page has been completely rendered

onUserRegisterFormDisplay

Registration from is displayed

onWallDisplay

Wall entry is processed for display

onMessageDisplay

Process inbox message for display

onDiscussionDisplay

Discussion entry is processed for display

onBulletinDisplay

Group bulletin entry is processed for display

Profile

onProfileInit

New user being registered with ApnaCafe

onProfileDisplay

Render application box in user profile

onProfileStatusUpdate

User status has been updated

onProfileAvatarUpdate

User avatar has been updated

Groups

onGroupCreate

New group created

onGroupDisable

When a group is disable

onGroupJoin

User join a group

onGroupJoinApproved

User join request approved

onGroupLeave

When user leave a group or removed by the group's admin

---

Event: onSystemStart

Description

This event trigger before any controller is called

Params

no params.

Examples

e.g.

function onSystemStart( ) 
{
   /*
      perform your triggered action here.
   */
}

---

Event: onSystemEnd

Description

This event trigger after all controller is called. (This trigger is not available yet)

Params

No Params.

Examples

e.g.

function onSystemEnd( ) 
{
   /*
      perform your triggered action here.
   */
}

---

Event: onUserRegisterFormDisplay

function onUserRegisterFormDisplay(&$form) 
{
  $invite = JRequest::getVar('inviteId', '', 'COOKIE');
  $text = JString::str_ireplace('</form>', '<input type="hidden" name="invite" value="'. $invite .'"></form>', $text);
}

stdClass Object
(
    [id] => 130
    [contentid] => 66
    [post_by] => 66
    [ip] => 127.0.0.1
    [comment] => 123 <a> 456
    [date] => 2009-02-03 10:33:49
    [published] => 1
    [type] => user
    [name] => Rwar
)

function onWallDisplay( &$wallContent) 
{
  CError::assert( $wallContent->comment, '', '!empty', __FILE__ , __LINE__ );
  $row->comment = $this->_filterText($wallContent->comment);
}

Description

Process each message when displaying the inbox messages.

Params

• Message - message object, passed by reference, consist of the following properties.

1. id - int, id of the message
2. from - int, member id of the message's sender.
3. parent - int, the parent of this message.
4. deleted - boolean, indicate if that message is deleted or not.
5. from_name - string, sender's name.
6. posted_on - string, date of the message is sent on.
7. subject - string, title of the message.
8. body - string, content of the message.
9. to - int, member id of the message's recipient.
10. to_deleted - boolean.
11. is_read - boolean, flag the message as read or unread.

e.g.

stdClass Object
(
    [id] => 29
    [from] => 62
    [parent] => 29
    [deleted] => 0
    [from_name] => admin
    [posted_on] => 2009-01-15 10:31:49
    [subject] => olololol
    [body] => testing
    [to] => 66
    [to_deleted] => 0
    [is_read] => 1
)

 

Examples

e.g.

function onMessageDisplay( &$message ) 
{
  CError::assert( $message->body, '', '!empty', __FILE__ , __LINE__ );
  $row->body = $this->_filterText($message->body);
}

Description

This event trigger before the group discussion is display.

Params

• Discussion - Discussion object, passed by reference.

1. id - int, id of the discussion.
2. groupid - int, id of the group.
3. creator - int, id of the creator.
4. created - string, date created.
5. title - string, title of the discussion.
6. message - string, message.

e.g.

CTableDiscussion Object
(
    [id] => 8
    [groupid] => 69
    [creator] => 66
    [created] => 2009-02-17 07:08:12
    [title] => testing discussion title
    [message] => testing discussion content
)

 

Examples

e.g.

function onDiscussionDisplay( &$discussion ) 
{
  CError::assert( $discussion->message, '', '!empty', __FILE__ , __LINE__ );
  $row->message = $this->_filterText($discussion->message);
 
}

CTableBulletin Object
(
    [id] => 57
    [groupid] => 69
    [created_by] => 66
    [published] => 1
    [title] => testing title
    [message] => testing message
    [date] => 2009-02-17 09:07:18
)

function onBulletinDisplay( &$bulletin ) 
{
  CError::assert( $bulletin->message, '', '!empty', __FILE__ , __LINE__ );
  $row->message = $this->_filterText($bulletin->message);
}

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.
• 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');
}

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.

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

1. from the same application (app)
2. with the same title
3. with the same cid

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

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 ApnaCafe 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".

Advance newsfeed formatting

The newsfeed system also support developer assigned replacement rule.

WIP

User Points System

ApnaCafe 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 'ApnaCafe_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 :

<?xml version="1.0" encoding="utf-8"?>
<ApnaCafe>
     <component>your component name</component>
     <rules>
          <rule>
        <name>your action name</name>
        <description>your description about the action</description>
        <action_string>your unique action string.</action_string>
        <publish>whether to publish the rule or not. true or false</publish>
        <points>points given to this action.</points>
        <access_level>user access level. For registered user, use 1.</access_level>          
          </rule>
     </rules>
</ApnaCafe>

For example,

<?xml version="1.0" encoding="utf-8"?>
<ApnaCafe>
     <component>com_community</component>
     <rules>
          <rule>
        <name>Add Application</name>
        <description>Give points when registered user add new application.</description>
        <action_string>com_community.application.add</action_string>
        <publish>true</publish>
        <points>1</points>
        <access_level>1</access_level>       
          </rule>
          <rule>
        <name>Remove Application</name>
        <description>Deduct points when registered user remove application.</description>
        <action_string>com_community.application.remove</action_string>
        <publish>true</publish>
        <points>0</points>
        <access_level>1</access_level>
           </rule>
     </rules>
</ApnaCafe>

For the access_level, these are the value you should use.

• 0 => Public
• 1 => Registered
• 2 => Special

Assuming you have included this ' ApnaCafe_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\ ApnaCafe_rule.xml'.

Now go to your ApnaCafe 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 'ApnaCafe_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 ApnaCafe backend in UserPoints page. Below screen is where you can modify your rule's attributes.