Sinisakrisan (Talk | contribs) (→en-GB.plg_system_example.sys.ini) |
Sinisakrisan (Talk | contribs) (→Community Plugin) |
||
Line 185: | Line 185: | ||
Please take note that in .xml file of Community plugin, you must add two additional elements | Please take note that in .xml file of Community plugin, you must add two additional elements | ||
* '''isapplication''' - If set to true, the application can be selected by user from the front-end | * '''isapplication''' - If set to true, the application can be selected by user from the front-end | ||
− | * '''Field coreapp''' - Within the | + | * '''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. |
====Accessing parameter==== | ====Accessing parameter==== |
Revision as of 13:58, 23 January 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
- example.php - the main plugin file
- example.xml - the plugin xml file
- en-GB.plg_system_example.ini - main language file
- en-GB.plg_system_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 wollow 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"
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 two 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.
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.