Difference between revisions of "Plugin Tutorials"

(Undo revision 1870 by Patricia Schmidt (talk))
 
(81 intermediate revisions by 2 users not shown)
Line 1: Line 1:
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
+
==Overview==
 +
Plugins allow developers the ability to extend JomSocial and provide new functionality or feature that is not already available in the core or to use the features that are available and extend them even more. A JomSocial plugin is essentially a normal Joomla plugin that can be installed, uninstalled, and managed just like every other Joomla plugin. JomSocial provides plenty of [[API Events|system hooks]] or trigger points which your plugin will use to add new functionality.<br/>
 +
You can create any type of plugin, but the most common types are:
 +
* '''System Plugin'''
 +
* '''User Plugin
 +
* '''Community Plugin'''
  
A plugin can either be
+
===Tutorials===
*system plugin or
+
If you already know how to [http://docs.joomla.org/Plugin_Development create Joomla Plugins] then creating a JomSocial plugin would be rather easy task. <br/>
* profile plugin
+
At very least, you will need the following four (4) files:
 +
# '''example.php''' - Main Plugin File.
 +
# '''example.xml''' - Plugin XML File.
 +
# '''en-GB.plg_type_example.ini''' - Main Language File.
 +
# '''en-GB.plg_type_example.sys.ini''' - System Language File.
  
===System plugin===
+
===System Plugin===
System plugin allows you to perform various system wide task.
+
  
===Profile plugin===
+
System plugin allows you to perform various system-wide tasks. In this tutorial, we are going to create a custom system plugin that will be triggered after [http://docs.joomla.org/Plugin/Events/System#onAfterRoute onAfterRoute Joomla system event]. In your main PHP file, you will need to
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.
+
# Include a JomSocial core file.
 +
# Declare a class with plgSystem[Plugin name] format. This class should extend the JPlugin class.
  
===Tutorials===
+
====example.php====
Creating a JomSocial plugin is easy. At least, you will need 2 files, the plugin php file and its xml file.
+
<syntaxhighlight lang="php">
 +
defined('_JEXEC') or die('Restricted access');
 +
if (! class_exists ( 'plgSystemExample' )) {
 +
class plgSystemExample extends JPlugin {
 +
/**
 +
* Method construct
 +
*/
 +
function plgSystemExample($subject, $config) {
 +
parent::__construct($subject, $config);
 +
JPlugin::loadLanguage ( 'plg_system_example', JPATH_ADMINISTRATOR ); // only use if theres any language file
 +
include_once( JPATH_ROOT .'/components/com_community/libraries/core.php' ); // loading the core library now
 +
}
 +
 +
/**
 +
* This event is triggered after the framework has loaded and the application initialise method has been called.
 +
*/
 +
public function onAfterRoute() {
 +
 +
// Do something here :)
 +
 +
}
 +
}
 +
}
 +
</syntaxhighlight>
 +
<br />
  
====Sample of system plugin ====
+
====example.xml====
'''example.php'''
+
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="utf-8"?>
 +
<extension version="2.5" type="plugin" group="system" method="upgrade">
 +
<name>System - Example</name>
 +
<author>Author Name</author>
 +
<creationDate>February 2013</creationDate>
 +
<copyright>Copyright 2013 - Your Company</copyright>
 +
<license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
 +
<authorEmail>[email protected]</authorEmail>
 +
<authorUrl>http://www.site.name</authorUrl>
 +
<version>x.y.z</version>
 +
 
 +
<description>PLG_EXAMPLE_DESCRIPTION</description>
 +
<languages>
 +
    <language tag="en-GB">en-GB.plg_system_example.ini</language>
 +
<language tag="en-GB">en-GB.plg_system_example.sys.ini</language>
 +
</languages>
 +
<files>
 +
<file plugin="example">example.php</file>
 +
</files>
 +
</extension>
 +
</syntaxhighlight>
 +
<br />
  
In your main php file, you will need to
+
====en-GB.plg_system_example.ini====
* include JomSocial core file
+
<syntaxhighlight lang="php">
* declare a class with plgCommunity[Plugin name] format. This class should extends CApplications class.
+
PLG_EXAMPLE_TITLE="Title of our plugin"
 +
</syntaxhighlight>
 +
<br />
 +
 
 +
====en-GB.plg_system_example.sys.ini====
 +
<syntaxhighlight lang="php">
 +
PLG_EXAMPLE_DESCRIPTION="Description of our plugin"
 +
</syntaxhighlight>
 +
<br />
 +
 
 +
==User Plugin==
 +
In this turtorial, we will create the user plugin that will utilize the Joomla [http://docs.joomla.org/Plugin/Events/User#onUserAfterSave onUserAfterSave] hook to make an action in the activity stream after a new user is created. As with the system plugin, you will need a minimum of four (4) files, and follow the same structure. As before, in your main php file you will need to:
 +
# Include the JomSocial core file.
 +
# Declare a class with plgUser[Plugin name] format. This class should extend the JPlugin class.
 +
 
 +
====example.php====
 
<syntaxhighlight lang="php">
 
<syntaxhighlight lang="php">
 
defined('_JEXEC') or die('Restricted access');
 
defined('_JEXEC') or die('Restricted access');
require_once JPATH_ROOT.'/components/com_community/libraries/core.php';
+
jimport('joomla.plugin.plugin');
   
+
 
 +
class plgUserExample extends JPlugin {
 +
 
 +
    public function plgUserExample(& $subject, $config) {
 +
        parent::__construct($subject, $config);
 +
    }
 +
 
 +
    public function onUserAfterSave($user, $isnew, $success, $msg) {
 +
        if ($isnew) {
 +
            $this->addStream($user['id']);
 +
        }
 +
    }
 +
 
 +
    private function addStream($userid) {
 +
        $lang = & JFactory::getLanguage();
 +
        $lang->load('plg_user_example', JPATH_ADMINISTRATOR);
 +
 
 +
        require_once JPATH_ROOT .'/components/com_community/libraries/core.php';
 +
        CFactory::load('libraries', 'activities');
 +
        $my = & CFactory::getUser($userid);
 +
 
 +
        $act = new stdClass();
 +
        $act->cmd = 'members.register';
 +
        $act->actor = $my->id;
 +
        $act->target = 0;
 +
        $act->title = JText::_($this->params->get('activitymessage', 'PLG_EXAMPLE_NEW_USER_REGISTERED'));
 +
        $act->content = '';
 +
        $act->app = 'profile';
 +
        $act->cid = 0;
 +
        $act->params = '';
 +
 
 +
        CActivityStream::add($act);
 +
    }
 +
 
 +
}
 +
</syntaxhighlight>
 +
<br />
 +
 
 +
====example.xml====
 +
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="utf-8"?>
 +
<extension version="2.5" type="plugin" group="user" method="upgrade">
 +
    <name>User - Example</name>
 +
    <author>Author Name</author>
 +
    <creationDate>Jan 2013</creationDate>
 +
    <copyright>Copyright 2013 - Your Company</copyright>
 +
    <license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
 +
    <authorEmail>autho[email protected]</authorEmail>
 +
    <authorUrl>http://www.site.name</authorUrl>
 +
    <version>x.y.z</version>
 +
 +
    <description>PLG_EXAMPLE_DESCRIPTION</description>
 +
    <files>
 +
        <filename plugin="example">example.php</filename>
 +
    </files>
 +
 +
    <languages>
 +
        <language tag="en-GB">en-GB.plg_user_example.ini</language>
 +
        <language tag="en-GB">en-GB.plg_user_example.sys.ini</language>
 +
    </languages>
 +
 +
    <config>
 +
        <fields name="params">
 +
            <fieldset name="basic">
 +
                <field name="activitymessage" type="text" rows="3" cols="50" default="PLG_EXAMPLE_NEW_USER_REGISTERED" label="Activity message" description="Enter the message that you want to appear in the activity" />
 +
            </fieldset>
 +
        </fields>
 +
    </config>
 +
 +
</extension>
 +
</syntaxhighlight>
 +
<br />
 +
 
 +
====en-GB.plg_user_example.ini====
 +
<syntaxhighlight lang="php">
 +
PLG_EXAMPLE_TITLE="Name of our plugin"
 +
PLG_EXAMPLE_NEW_USER_REGISTERED = "became new member of site"
 +
</syntaxhighlight>
 +
<br />
 +
 
 +
====en-GB.plg_user_example.sys.ini====
 +
<syntaxhighlight lang="php">
 +
PLG_EXAMPLE_DESCRIPTION="Description of our plugin"
 +
</syntaxhighlight>
 +
<br />
 +
 
 +
===Sample Plugin===
 +
This plugin is freely available in [http://www.jomsocial.com/forum/extra-addons/2308-new-user-registration#12313 our forums]. Please note that you will need a valid subscription to see the forums and that the plugin code might differ.
 +
 
 +
==Community Plugin==
 +
The Community, or Profile, plugin, also known as an application, is the most widely used type of plugin in JomSocial. When you create a '''Community plugin''', individual site members will be able to select your plugin to be displayed on their profile page. Your plugin will be able to pull information from the user profile page and will have access to user various parameters. Please note that in the XML file of the Community plugin, you must add some additional elements.
 +
# '''isapplication''' - If set to true, the application can be selected by user from the front-end.
 +
# '''Field coreapp''' - Within the fields section, please add a field named '''coreapp'''. This allows the Admin to force this application to appear on all user profiles.
 +
# '''Field position''' - Within the fields section, please add a field named '''position'''. This will allow Admin to select the default position if the plugin is set as a core.
 +
As with the system plugin, it will need a minimum of four (4) files for the community plugin to work; however, we recommend that you to create another folder named exactly the same as the plugin. In this folder, we will store the plugin favicon, thumbnail, and eventually the '''config.xml''' file which will be used for the Frontend configuration of plugin options, as explained later through these tutorials.<br/>
 +
As before, in your main PHP file, you will need to:
 +
# Include JomSocial core file.
 +
# Declare a class with the format, plgCommunity[Plugin name]. Unlike the System and User plugins, this class should now extend CApplications class.
 +
 
 +
====example.php====
 +
<syntaxhighlight lang="php">
 +
defined('_JEXEC') or die('Restricted access');
 +
require_once JPATH_ROOT .'/components/com_community/libraries/core.php';
 +
 
 
class plgCommunityExample extends CApplications
 
class plgCommunityExample extends CApplications
 
{
 
{
var $name = 'Invite';
+
var $name = "Example";
var $_name = 'invite';
+
var $_name = 'example';
+
function plgCommunityExampl(& $subject, $config)
+
function plgCommunityExample(& $subject, $config)
 
{
 
{
 
parent::__construct($subject, $config);
 
parent::__construct($subject, $config);
 +
}
 +
 +
function onProfileDisplay()
 +
{
 +
ob_start();
 +
 +
echo 'Hello World';
 +
           
 +
$content = ob_get_contents();
 +
ob_end_clean();
 +
 +
return $content;
 
}
 
}
 
}
 
}
Line 37: Line 222:
 
<br />
 
<br />
  
'''example.xml'''
+
====example.xml====
 
<syntaxhighlight lang="xml">
 
<syntaxhighlight lang="xml">
< version="1.0" encoding="utf-8"?>
+
<?xml version="1.0" encoding="utf-8"?>
<install></install> < version="1.5" type="plugin" group="community">
+
<extension version="2.5" type="plugin" group="community" method="upgrade">
< Walls>
+
<name>Community - Example</name>
<author><</author>AzrulStudio>
+
<author>Author Name</author>
<creationdate><</creationdate>7 October 2008>
+
<creationDate>Febraury 2013</creationDate>
<copyright><</copyright>Copyright (C) 2008. All rights reserved.>
+
<copyright>Copyright 2013 - Your Company</copyright>
<license><</license>http://www.azrul.com>
+
<license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
<authoremail><</authoremail>support@azrul.com>
+
<authorEmail>author@email.com</authorEmail>
<authorurl><</authorurl>www.azrul.com>
+
<authorUrl>http://www.site.name</authorUrl>
<version><</version>1.0>
+
<version>x.y.z</version>
<isapplication><</isapplication>true>
+
<isapplication>true</isapplication>
<description><</description>Example for JomSocial © AzrulStudio 2008>
+
<files> </files>
+
<description>PLG_EXAMPLE_DESCRIPTION</description>
<<file></file> plugin="example">example.php>
+
<file><</file>example.xml>
+
<languages>
  <name="cache" type="list" default="0" label="Enable caching" description="Cache data">
+
<language tag="en-GB">en-GB.plg_community_example.ini</language>
  <value="0">No>
+
<language tag="en-GB">en-GB.plg_community_example.sys.ini</language>
  <value="1">Yes>
+
</languages>
<name="coreapp" type="list" default="0" label="Core Application"  
+
description="Causes this application to not appearin the users applications
+
<files>
list but it will allow this application to appear in the user profile
+
<file plugin="example">example.php</file>
automatically if selected.">
+
<folder>example</folder>
  <value="0">No>
+
</files>
  <value="1">Yes>
+
 +
<config>
 +
<fields name="params">
 +
<fieldset name="basic">
 +
<field 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>
 +
</field>
 +
<field name="position" type="list" default="content" label="Avalaible Positions" description="Select one or more available positions from the list.  You can use Ctrl-click to select more than one item.">
 +
<option value="content">Content</option>
 +
<option value="sidebar-top">Sidebar Top</option>
 +
<option value="sidebar-bottom">Sidebar Bottom</option>
 +
</field>
 +
</fieldset>
 +
</fields>
 +
</config>
 +
</extension>
 
</syntaxhighlight>
 
</syntaxhighlight>
 
<br />
 
<br />
  
Please take note that there is a few additional element
+
====en-GB.plg_community_example.ini====
* isapplication <br />
+
<syntaxhighlight lang="php">
If set to true, the application can be selected by user from the front-end
+
PLG_EXAMPLE_TITLE="Name of our plugin"
* Param coreapp <br />
+
</syntaxhighlight>
Within the params section, please add a param named 'coreapp'. This allow admin to force this application to appear on all user profile.
+
<br />
 +
 
 +
====en-GB.plg_community_example.sys.ini====
 +
<syntaxhighlight lang="php">
 +
PLG_EXAMPLE_DESCRIPTION="Description of the plugin'
 +
</syntaxhighlight>
 +
<br />
  
====Accessing parameter====
+
==Accessing Configuration Parameters==
There are 2 types of plugin parameters, the site plugin params and user params
+
There are two (2) types of plugin parameters: the site plugin params and user params.
  
=====Default system parameters =====
+
===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.
+
System parameters are settings that are specified by the server administrator. It cannot be changed by the user and the admin can only modify the setting from the Joomla Backend.
This params is loaded automatically and can be accessed right away.
+
The params are loaded automatically and can be accessed directly:
 
<syntaxhighlight lang="php">
 
<syntaxhighlight lang="php">
 
$db_name = $this->params->get('db_name', '');
 
$db_name = $this->params->get('db_name', '');
 
</syntaxhighlight>
 
</syntaxhighlight>
 
<br />
 
<br />
=====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.
+
===User Parameters===
 +
A '''User Parameter''' is params data that is specific to the current user. To define params, first create a file called '''config.xml''' inside the plugin folder.
 
<syntaxhighlight lang="php">
 
<syntaxhighlight lang="php">
// Sample config.xml
+
<?xml version="1.0" encoding="utf-8"?>
<version="1.0" encoding="utf-8"?>
+
<extension version="2.5" type="plugin" group="community">
<install></install> <version="1.5" type="plugin" group="community">
+
<params>
 
+
<param name="someparam" type="text" default="5" size="3" label="Some Param" description="Some Param that user can set" />
    <name="path" type="text" default="" label="Feed url"/>
+
</params>
      <name="count" type="text" default="5" label="Count"  />
+
</extension>
 
</syntaxhighlight>
 
</syntaxhighlight>
 
<br />
 
<br />
To use any user specific parameter, you will need to load it before you can use it. Just call
+
'''User-Specific''' parameter - load it by calling:
 
<syntaxhighlight lang="php">
 
<syntaxhighlight lang="php">
 
$this->loadUserParams();
 
$this->loadUserParams();
// After loading, userparams object (JParameters) will be available to yoi
+
// After loading, userparams object (JParameters) will be available to you
 
$path = $this->userparams->get('path', '');
 
$path = $this->userparams->get('path', '');
 
</syntaxhighlight>
 
</syntaxhighlight>
 
<br />
 
<br />
  
====Caching plugin content ====
+
==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.
+
JomSocial, by default, does not cache the return values for plugins. If any plugin wants to use any caching system, you can deploy the standard Joomla caching system.<br/><br/>
  
 
'''example'''
 
'''example'''
 
<syntaxhighlight lang="php">
 
<syntaxhighlight lang="php">
class plgCommunityTwitter extends CApplications
+
class plgCommunityExample extends CApplications
 
{
 
{
var $name = "Me on twitter";
+
var $name = "Example";
var $_name = 'twitter';
+
var $_name = 'example';
 
   
 
   
 
function onProfileDisplay()
 
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');
 
$cache =& JFactory::getCache('community');
$callback = array($this, '_getTwitterHTML');
+
$callback = array($this, '_getExampleHTML');
+
 
$content = $cache->call($callback, $username, $password,
+
$content = $cache->call($callback);
$this->params,
+
$user, $my);
+
+
 
return $content;  
 
return $content;  
 
}
 
}
 
   
 
   
function _getTwitterHTML($username, $password, &$params, &$user, &$my) {
+
function _getExampleHTML() {
/* Do the processing here */
+
ob_start();
 +
 +
echo 'Hello World';
 +
           
 +
$content = ob_get_contents();
 +
ob_end_clean();
 +
 
return $content;
 
return $content;
 
}
 
}
Line 143: Line 341:
 
<br />
 
<br />
  
=====Note=====
+
{{alert|<strong>Note:</strong>
*Get the cache object with 'community' community.
+
*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.
+
*The function that returns the final content should not try to get the '''user''' and '''my''' objects. Caller should instead pass this data to the function.
*Any css/js attachment should be attached outside the cached function.
+
*Any CSS/JS attachment should be attached outside the cached function.|alert-info}}

Latest revision as of 02:31, 12 March 2013

Overview

Plugins allow developers the ability to extend JomSocial and provide new functionality or feature that is not already available in the core or to use the features that are available and extend them even more. A JomSocial plugin is essentially a normal Joomla plugin that can be installed, uninstalled, and managed just like every other Joomla plugin. JomSocial provides plenty of system hooks or trigger points which your plugin will use to add new functionality.
You can create any type of plugin, but the most common types are:

  • System Plugin
  • User Plugin
  • Community Plugin

Tutorials

If you already know how to create Joomla Plugins then creating a JomSocial plugin would be rather easy task.
At very least, you will need the following four (4) files:

  1. example.php - Main Plugin File.
  2. example.xml - Plugin XML File.
  3. en-GB.plg_type_example.ini - Main Language File.
  4. en-GB.plg_type_example.sys.ini - System Language File.

System Plugin

System plugin allows you to perform various system-wide tasks. In this tutorial, we are going to create a custom system plugin that will be triggered after onAfterRoute Joomla system event. In your main PHP file, you will need to

  1. Include a JomSocial core file.
  2. Declare a class with plgSystem[Plugin name] format. This class should extend the JPlugin class.

example.php

defined('_JEXEC') or die('Restricted access');
if (! class_exists ( 'plgSystemExample' )) {
	class plgSystemExample extends JPlugin {
		/**
		 * Method construct
		 */ 
		function plgSystemExample($subject, $config) {
			parent::__construct($subject, $config);
				JPlugin::loadLanguage ( 'plg_system_example', JPATH_ADMINISTRATOR ); // only use if theres any language file
				include_once( JPATH_ROOT .'/components/com_community/libraries/core.php' ); // loading the core library now
		}
 
		/**
		 * This event is triggered after the framework has loaded and the application initialise method has been called.
		 */
		public function onAfterRoute() {
 
			// Do something here :)
 
		}
	}
}


example.xml

<?xml version="1.0" encoding="utf-8"?>
<extension version="2.5" type="plugin" group="system" method="upgrade">
	<name>System - Example</name>
	<author>Author Name</author>
	<creationDate>February 2013</creationDate>
	<copyright>Copyright 2013 - Your Company</copyright>
	<license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
	<authorEmail>[email protected]</authorEmail>
	<authorUrl>http://www.site.name</authorUrl>
	<version>x.y.z</version>
 
	<description>PLG_EXAMPLE_DESCRIPTION</description>
	<languages>
	    <language tag="en-GB">en-GB.plg_system_example.ini</language>
		<language tag="en-GB">en-GB.plg_system_example.sys.ini</language>
	</languages>
	<files>
		<file plugin="example">example.php</file>
	</files>
</extension>


en-GB.plg_system_example.ini

PLG_EXAMPLE_TITLE="Title of our plugin"


en-GB.plg_system_example.sys.ini

PLG_EXAMPLE_DESCRIPTION="Description of our plugin"


User Plugin

In this turtorial, we will create the user plugin that will utilize the Joomla onUserAfterSave hook to make an action in the activity stream after a new user is created. As with the system plugin, you will need a minimum of four (4) files, and follow the same structure. As before, in your main php file you will need to:

  1. Include the JomSocial core file.
  2. Declare a class with plgUser[Plugin name] format. This class should extend the JPlugin class.

example.php

defined('_JEXEC') or die('Restricted access');
jimport('joomla.plugin.plugin');
 
class plgUserExample extends JPlugin {
 
    public function plgUserExample(& $subject, $config) {
        parent::__construct($subject, $config);
    }
 
    public function onUserAfterSave($user, $isnew, $success, $msg) {
        if ($isnew) {
            $this->addStream($user['id']);
        }
    }
 
    private function addStream($userid) {
        $lang = & JFactory::getLanguage();
        $lang->load('plg_user_example', JPATH_ADMINISTRATOR);
 
        require_once JPATH_ROOT .'/components/com_community/libraries/core.php';
        CFactory::load('libraries', 'activities');
        $my = & CFactory::getUser($userid);
 
        $act = new stdClass();
        $act->cmd = 'members.register';
        $act->actor = $my->id;
        $act->target = 0;
        $act->title = JText::_($this->params->get('activitymessage', 'PLG_EXAMPLE_NEW_USER_REGISTERED'));
        $act->content = '';
        $act->app = 'profile';
        $act->cid = 0;
        $act->params = '';
 
        CActivityStream::add($act);
    }
 
}


example.xml

<?xml version="1.0" encoding="utf-8"?>
<extension version="2.5" type="plugin" group="user" method="upgrade">
    <name>User - Example</name>
    <author>Author Name</author>
    <creationDate>Jan 2013</creationDate>
    <copyright>Copyright 2013 - Your Company</copyright>
    <license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
    <authorEmail>[email protected]</authorEmail>
    <authorUrl>http://www.site.name</authorUrl>
    <version>x.y.z</version>
 
    <description>PLG_EXAMPLE_DESCRIPTION</description>
    <files>
        <filename plugin="example">example.php</filename>
    </files>
 
    <languages>
        <language tag="en-GB">en-GB.plg_user_example.ini</language>
        <language tag="en-GB">en-GB.plg_user_example.sys.ini</language>
    </languages>
 
    <config>
        <fields name="params">
            <fieldset name="basic">
                <field  name="activitymessage" type="text" rows="3" cols="50" default="PLG_EXAMPLE_NEW_USER_REGISTERED" label="Activity message" description="Enter the message that you want to appear in the activity" />
            </fieldset>
        </fields>
    </config>
 
</extension>


en-GB.plg_user_example.ini

PLG_EXAMPLE_TITLE="Name of our plugin"
PLG_EXAMPLE_NEW_USER_REGISTERED = "became new member of site"


en-GB.plg_user_example.sys.ini

PLG_EXAMPLE_DESCRIPTION="Description of our plugin"


Sample Plugin

This plugin is freely available in our forums. Please note that you will need a valid subscription to see the forums and that the plugin code might differ.

Community Plugin

The Community, or Profile, plugin, also known as an application, is the most widely used type of plugin in JomSocial. When you create a Community plugin, individual site members will be able to select your plugin to be displayed on their profile page. Your plugin will be able to pull information from the user profile page and will have access to user various parameters. Please note that in the XML file of the Community plugin, you must add some additional elements.

  1. isapplication - If set to true, the application can be selected by user from the front-end.
  2. Field coreapp - Within the fields section, please add a field named coreapp. This allows the Admin to force this application to appear on all user profiles.
  3. Field position - Within the fields section, please add a field named position. This will allow Admin to select the default position if the plugin is set as a core.

As with the system plugin, it will need a minimum of four (4) files for the community plugin to work; however, we recommend that you to create another folder named exactly the same as the plugin. In this folder, we will store the plugin favicon, thumbnail, and eventually the config.xml file which will be used for the Frontend configuration of plugin options, as explained later through these tutorials.
As before, in your main PHP file, you will need to:

  1. Include JomSocial core file.
  2. Declare a class with the format, plgCommunity[Plugin name]. Unlike the System and User plugins, this class should now extend CApplications class.

example.php

defined('_JEXEC') or die('Restricted access');
require_once JPATH_ROOT .'/components/com_community/libraries/core.php';
 
class plgCommunityExample extends CApplications
{
	var $name = "Example";
	var $_name = 'example';
 
	function plgCommunityExample(& $subject, $config)
	{
		parent::__construct($subject, $config);
	}
 
	function onProfileDisplay()
	{
		ob_start();
 
			echo 'Hello World'; 
 
		$content	= ob_get_contents();
		ob_end_clean();
 
		return $content;
	}
}


example.xml

<?xml version="1.0" encoding="utf-8"?>
<extension version="2.5" type="plugin" group="community" method="upgrade">
	<name>Community - Example</name>
	<author>Author Name</author>
	<creationDate>Febraury 2013</creationDate>
	<copyright>Copyright 2013 - Your Company</copyright>
	<license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
	<authorEmail>[email protected]</authorEmail>
	<authorUrl>http://www.site.name</authorUrl>
	<version>x.y.z</version>
	<isapplication>true</isapplication>
 
	<description>PLG_EXAMPLE_DESCRIPTION</description>
 
	<languages>
		<language tag="en-GB">en-GB.plg_community_example.ini</language>
		<language tag="en-GB">en-GB.plg_community_example.sys.ini</language>
	</languages>
 
	<files>
		<file plugin="example">example.php</file>
		<folder>example</folder>
	</files>
 
	<config>
		<fields name="params">
			<fieldset name="basic">
				<field 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>
				</field>
				<field name="position" type="list" default="content" label="Avalaible Positions" description="Select one or more available positions from the list.  You can use Ctrl-click to select more than one item.">
					<option value="content">Content</option>
					<option value="sidebar-top">Sidebar Top</option>
					<option value="sidebar-bottom">Sidebar Bottom</option>
				</field>
			</fieldset>
		</fields>
	</config>
</extension>


en-GB.plg_community_example.ini

PLG_EXAMPLE_TITLE="Name of our plugin"


en-GB.plg_community_example.sys.ini

PLG_EXAMPLE_DESCRIPTION="Description of the plugin'


Accessing Configuration Parameters

There are two (2) types of plugin parameters: the site plugin params and user params.

Default System Parameters

System parameters are settings that are specified by the server administrator. It cannot be changed by the user and the admin can only modify the setting from the Joomla Backend. The params are loaded automatically and can be accessed directly:

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


User Parameters

A User Parameter is params data that is specific to the current user. To define params, first create a file called config.xml inside the plugin folder.

<?xml version="1.0" encoding="utf-8"?>
<extension version="2.5" type="plugin" group="community">
	<params>
		<param name="someparam" type="text" default="5" size="3" label="Some Param" description="Some Param that user can set" />		
	</params>
</extension>


User-Specific parameter - load it by calling:

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


Caching Plugin Content

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

example

class plgCommunityExample extends CApplications
{
	var $name 		= "Example";
	var $_name		= 'example';	
 
	function onProfileDisplay()
	{
		$cache =& JFactory::getCache('community');
		$callback = array($this, '_getExampleHTML');
 
		$content = $cache->call($callback);
		return $content; 
	}
 
	function _getExampleHTML() {
		ob_start();
 
			echo 'Hello World'; 
 
		$content	= ob_get_contents();
		ob_end_clean();
 
		return $content;
	}


Note:
  • Get the cache object with community community.
  • The function that returns the final content should not try to get the user and my objects. Caller should instead pass this data to the function.
  • Any CSS/JS attachment should be attached outside the cached function.