Plugin Tutorials

Revision as of 01:43, 8 March 2013 by Patricia Schmidt (Talk | contribs)

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, creating JomSocial plugin would be rather easy task.
At very least, you will need 4 files

  1. example.php - the main plugin file
  2. example.xml - the 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 task.
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

  • include JomSocial core file
  • declare a class with plgSystem[Plugin name] format. This class should extends 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 activity stream after new user is created. As with system plugin, we will need minimum 4 files, so we follow the same structure
As usual in your main php file, you will need to

  • include JomSocial core file
  • declare a class with plgUser[Plugin name] format. This class should extends 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"


Plugin Sample

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

Community Plugin

Community, or profile plugin, also known as application, is most widely used type of plugin in JomSocial. When you create a Community 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.
Please take note that in .xml file of Community plugin, you must add somel 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 allow admin to force this application to appear on all user profile.
  • Field position - Within the fields section, please add a field named position. This will allow admin to select the default position if plugin is set as core.

As with system plugin, we will need minimum 4 files and community plugin will work just fine, however, we recommend you to create another folder named exactly as plugin. In this folder, we will store the plugin favicon, thumbnail and eventually the config.xml file which will be used for Front End configuration of plugin options, and explained later through this tutorials.
As usual in your main php file, you will need to

  • include JomSocial core file
  • declare a class with plgCommunity[Plugin name] format. Unlike System and User plugin, 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 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.

<?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>


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 you
$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 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 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.