J3.x:Creating a Plugin for Joomla

The plugin structure for Joomla! 1.5 was very flexible and powerful. Not only can plugins be used to handle events triggered by the core application and extensions, but plugins can also be used to make third party extensions extensible and powerful. The main changes from Joomla 1.5 to the 2.5/3.x series was the change in the names of events.

This How-To should provide you with the basics of what you need to know to develop your own plugin. Most plugins consist of just a single code file but to correctly install the plugin code it must be packaged into an installation file which can be processed by the Joomla! installer.

Creating the Installation File

As with all extensions in Joomla!, plugins are easily installed as a .zip file (.tar.gz is also supported) but a correctly formatted XML file must be included. As an example, here is the XML installation file for the categories search plugin.

<?xml version="1.0" encoding="utf-8"?>
<extension version="3.1" type="plugin" group="search">
	<name>plg_search_categories</name>
	<author>Joomla! Project</author>
	<creationDate>November 2005</creationDate>
	<copyright>Copyright (C) 2005 - 2013 Open Source Matters. All rights reserved.</copyright>
	<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
	<authorEmail>admin@joomla.org</authorEmail>
	<authorUrl>www.joomla.org</authorUrl>
	<version>3.1.0</version>
	<description>PLG_SEARCH_CATEGORIES_XML_DESCRIPTION</description>
	<files>
		<filename plugin="categories">categories.php</filename>
		<filename>index.html</filename>
	</files>
	<languages>
		<language tag="en-GB">en-GB.plg_search_categories.ini</language>
		<language tag="en-GB">en-GB.plg_search_categories.sys.ini</language>
	</languages>
	<config>
		<fields name="params">

			<fieldset name="basic">
				<field name="search_limit" type="text"
					default="50"
					description="JFIELD_PLG_SEARCH_SEARCHLIMIT_DESC"
					label="JFIELD_PLG_SEARCH_SEARCHLIMIT_LABEL"
					size="5"
				/>

				<field name="search_content" type="radio"
					default="0"
					description="JFIELD_PLG_SEARCH_ALL_DESC"
					label="JFIELD_PLG_SEARCH_ALL_LABEL"
				>
					<option value="0">JOFF</option>
					<option value="1">JON</option>
				</field>

				<field name="search_archived" type="radio"
					default="0"
					description="JFIELD_PLG_SEARCH_ARCHIVED_DESC"
					label="JFIELD_PLG_SEARCH_ARCHIVED_LABEL"
				>
					<option value="0">JOFF</option>
					<option value="1">JON</option>
				</field>
			</fieldset>

		</fields>
	</config>
</extension>

As you can see, the system is similar to other Joomla! XML installation files. You only have to look out for the group="xxx" entry in the <install> tag and the extended information in the <filename> tag. This information tells Joomla! into which folder to copy the file and to which group the plugin should be added.

If you are creating a plugin that responds to existing core events, the group="xxx" attribute would be changed to reflect the name of existing plugin folder for the event type you wish to augment. e.g. group="authentication" or group="user". See Plugin/Events for a complete list of existing core event categories. In creating a new plugin to respond to core events it is important that your plugin's name is unique and does not conflict with any of the other plugins that may also be responding to the core event you wish to service as well.

If you are creating a plugin to respond to non-core system events your choice for the group="xxx" tag should be different than any of the existing core categories.

Tip If you add the attribute method="upgrade" to the tag install, this plugin can be installed without uninstalling an earlier version. All existing files will be overwritten, but old files will not be deleted.

Creating the Plugin

The object-oriented way of writing plugins involves writing a subclass of JPlugin, a base class that implements the basic properties of plugins. In your methods, the following properties are available:

• $this->params: the parameters set for this plugin by the administrator
• $this->_name: the name of the plugin
• $this->_type: the group (type) of the plugin

In the following code example, <PluginGroup> represents the group (type) of the plugin, and <PluginName> represents its name. Note that class and function names in PHP are case-insensitive.

<?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

class plg<PluginGroup><PluginName> extends JPlugin
{
/**
 * Constructor - note in Joomla 2.5 PHP4.x is no longer supported so we can use this.
 *
 * @access      protected
 * @param       object  $subject The object to observe
 * @param       array   $config  An array that holds the plugin configuration
 */
public function __construct(& $subject, $config)
{
	parent::__construct($subject, $config);
	$this->loadLanguage();
}
/**
 * Plugin method with the same name as the event will be called automatically.
 */
 function <EventName>()
 {
    $app = JFactory::getApplication();

        // Plugin code goes here.
        // You can access parameters via $this->params.
    return true;
 }
}
?>

Using Plugins in Your Code

Now that you've created your plugin, you will probably want to call it in your code. You might not: the Joomla! core has a number of built-in events that you might want your plugin code to be registered to. In that case you don't need to do the following.

If you want to trigger an event then you use code like this:

$dispatcher = JDispatcher::getInstance();
$results = $dispatcher->trigger( '<EventName>', <ParameterArray> );

It is important to note that the parameters have to be in an array. The plugin function itself will get the parameters as single values. The return value will consist of an array of return values from the different plugins (so it can also contain multilevel arrays).

If you are creating a plugin for a new, non-core event, remember to activate your plugin after you install it. Precede any reference to your new plugin with the JPluginHelper::importPlugin() command.