Difference between revisions of "Plugin Tutorials"

(User Parameters)
m (Reverted edits by Patricia Schmidt (talk) to last revision by Sinisakrisan)
Line 1: Line 1:
 
==Overview==
 
==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/>
+
Plugins allow developers to extend JomSocial and provide new functionality or feature that is not already available in the core, or use the features that are available, to extend them even more.. A plugin is essentially a normal Joomla! plugin that can be installed, uninstalled and managed just like every other Joomla! plugin. JomSocial provide plenty of [[API Events|system hooks]], or trigger point which your plugin will use to add new functionality.<br/>
You can create any type of plugin, but the most common types are:
+
You can create any type of plugin but most common types are:
* '''System Plugin'''
+
* '''System plugin'''
 
* '''User Plugin
 
* '''User Plugin
 
* '''Community Plugin'''
 
* '''Community Plugin'''
  
===Tutorials===
+
==Tutorials==
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/>
+
If you already know how to [http://docs.joomla.org/Plugin_Development create Joomla Plugins], creating JomSocial plugin would be rather easy task. <br/>
At very least, you will need the following four (4) files:
+
At very least, you will need 4 files
# '''example.php''' - Main Plugin File.
+
# '''example.php''' - the main plugin file
# '''example.xml''' - Plugin XML File.
+
# '''example.xml''' - the plugin xml file
# '''en-GB.plg_type_example.ini''' - Main Language File.
+
# '''en-GB.plg_type_example.ini''' - main language file
# '''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 task.<br/>
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
+
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] <br/>
# Include a JomSocial core file.
+
In your main php file, you will need to
# Declare a class with plgSystem[Plugin name] format. This class should extend the JPlugin class.
+
* include JomSocial core file
 +
* declare a class with plgSystem[Plugin name] format. This class should extends JPlugin class.
  
 
====example.php====
 
====example.php====
Line 84: Line 85:
 
<br />
 
<br />
  
==User Plugin==
+
==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:
+
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 activity stream after new user is created. As with system plugin, we will need minimum 4 files, so we follow the same structure<br/>
# Include the JomSocial core file.
+
As usual in your main php file, you will need to
# Declare a class with plgUser[Plugin name] format. This class should extend the JPlugin class.
+
* include JomSocial core file
 +
* declare a class with plgUser[Plugin name] format. This class should extends JPlugin class.
  
 
====example.php====
 
====example.php====
Line 179: Line 181:
 
<br />
 
<br />
  
===Sample Plugin===
+
=====Plugin Sample=====
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.
+
This plugin is freely available at [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 plugin code might differ.
  
 
==Community Plugin==
 
==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.
+
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. <br/>
# '''isapplication''' - If set to true, the application can be selected by user from the front-end.
+
Please take note that in .xml file of Community plugin, you must add somel additional elements
# '''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.
+
* '''isapplication''' - If set to true, the application can be selected by user from the front-end
# '''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.
+
* '''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.
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/>
+
* '''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 before, in your main PHP file, you will need to:
+
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.<br/>
# Include JomSocial core file.
+
As usual in your main php file, you will need to
# Declare a class with the format, plgCommunity[Plugin name]. Unlike the System and User plugins, this class should now extend CApplications class.  
+
* 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====
 
====example.php====
Line 280: Line 283:
  
 
==Accessing Configuration Parameters==
 
==Accessing Configuration Parameters==
There are two (2) types of plugin parameters: the site plugin params and user params.
+
There are 2 types of plugin parameters, the site plugin params and user params
  
===Default System Parameters===
+
=====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.
+
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.
The params are loaded automatically and can be accessed directly:
+
This params is loaded automatically and can be accessed right away.
 
<syntaxhighlight lang="php">
 
<syntaxhighlight lang="php">
 
$db_name = $this->params->get('db_name', '');
 
$db_name = $this->params->get('db_name', '');
Line 290: Line 293:
 
<br />
 
<br />
  
===User Parameters===
+
=====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.
+
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.
 
<syntaxhighlight lang="php">
 
<syntaxhighlight lang="php">
 
<?xml version="1.0" encoding="utf-8"?>
 
<?xml version="1.0" encoding="utf-8"?>
Line 301: Line 304:
 
</syntaxhighlight>
 
</syntaxhighlight>
 
<br />
 
<br />
'''User-Specific''' parameter - load it by calling:
+
To use any user specific parameter, you will need to load it before you can use it. Just call
 
<syntaxhighlight lang="php">
 
<syntaxhighlight lang="php">
 
$this->loadUserParams();
 
$this->loadUserParams();
Line 309: Line 312:
 
<br />
 
<br />
  
==Caching Plugin Content==
+
==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.<br/><br/>
+
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'''
 
'''example'''
Line 341: Line 344:
 
<br />
 
<br />
  
{{alert|<strong>Note:</strong>
+
=====Note=====
*Get the cache object with '''community''' community.
+
*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.
+
*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.|alert-info}}
+
*Any css/js attachment should be attached outside the cached function.

Revision as of 02:02, 12 March 2013

Overview

Plugins allow developers to extend JomSocial and provide new functionality or feature that is not already available in the core, or use the features that are available, to extend them even more.. A plugin is essentially a normal Joomla! plugin that can be installed, uninstalled and managed just like every other Joomla! plugin. JomSocial provide plenty of system hooks, or trigger point which your plugin will use to add new functionality.
You can create any type of plugin but 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.