Plugin Tutorials

Revision as of 03:16, 23 January 2013 by Sinisakrisan (Talk | contribs)

==Overview==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 or
  • 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 files, the plugin php file and its xml file.

Example of system plugin

In this tutorial, we are going to create a custom system plugin that will be triggered 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_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>


Example of Profile Plugin

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.

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


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.