Difference between revisions of "Plugin Tutorials"

(Tutorials)
(System Plugin)
Line 14: Line 14:
 
# '''en-GB.plg_type_example.sys.ini''' - System 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 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
 
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
 
  Include a JomSocial core file.
 
  Include a JomSocial core file.

Revision as of 05:33, 9 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

Include a JomSocial core file.
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:

Include the JomSocial core file.
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.

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

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.