Difference between revisions of "Plugin Developer Overview"
From Joomla! Documentation
(Update function name) |
(Update some references) |
||
Line 1: | Line 1: | ||
+ | {{review|technical|This is way more out of date than I thought :( - going to need serious work}} | ||
{{version|1.5,2.5,3.1}} | {{version|1.5,2.5,3.1}} | ||
Joomla! 1.5 introduced the <code>JPlugin</code> class. In the effort to move Joomla! toward a more efficient object-oriented framework, a new plugin system has been developed which follows the [[wikipedia:Observer pattern|Observer pattern]]. Plugins are observer classes that attach to a global event dispatcher object in the Joomla! core. What does this mean in English? It means that either the Joomla! core or a third party component or module can trigger an event which causes one or more plugins to execute some code. | Joomla! 1.5 introduced the <code>JPlugin</code> class. In the effort to move Joomla! toward a more efficient object-oriented framework, a new plugin system has been developed which follows the [[wikipedia:Observer pattern|Observer pattern]]. Plugins are observer classes that attach to a global event dispatcher object in the Joomla! core. What does this mean in English? It means that either the Joomla! core or a third party component or module can trigger an event which causes one or more plugins to execute some code. | ||
Line 6: | Line 7: | ||
The implementation of the plugin system is that of an observer pattern. It has two parts, an observer class, <code>JPlugin</code>, and an observable class, <code>JEventDispatcher</code> (changed to <code>JEventDispatcher</code> in {{JVer|3.x}}). | The implementation of the plugin system is that of an observer pattern. It has two parts, an observer class, <code>JPlugin</code>, and an observable class, <code>JEventDispatcher</code> (changed to <code>JEventDispatcher</code> in {{JVer|3.x}}). | ||
− | <source lang="php">/** | + | <source lang="php"> |
+ | /** | ||
* JPlugin Class | * JPlugin Class | ||
* | * | ||
− | * @package Joomla. | + | * @package Joomla.Platform |
− | * @subpackage | + | * @subpackage Plugin |
− | * @since 1 | + | * @since 11.1 |
*/ | */ | ||
− | class JPlugin extends | + | class JPlugin extends JEvent |
{ | { | ||
/** | /** | ||
* Constructor | * Constructor | ||
− | * | + | * |
− | * | + | * @param object &$subject The object to observe |
− | * | + | * @param array $config An optional associative array of configuration settings. |
− | * | + | * Recognized key values include 'name', 'group', 'params', 'language' |
− | * | + | * (this list is not meant to be comprehensive). |
− | * | + | * |
− | * @since 1 | + | * @since 11.1 |
*/ | */ | ||
− | function | + | public function __construct(&$subject, $config = array()) |
{ | { | ||
− | + | // Get the parameters. | |
− | + | if (isset($config['params'])) | |
+ | { | ||
+ | if ($config['params'] instanceof JRegistry) | ||
+ | { | ||
+ | $this->params = $config['params']; | ||
+ | } | ||
+ | else | ||
+ | { | ||
+ | $this->params = new JRegistry; | ||
+ | $this->params->loadString($config['params']); | ||
+ | } | ||
+ | } | ||
+ | |||
+ | // Get the plugin name. | ||
+ | if (isset($config['name'])) | ||
+ | { | ||
+ | $this->_name = $config['name']; | ||
+ | } | ||
+ | |||
+ | // Get the plugin type. | ||
+ | if (isset($config['type'])) | ||
+ | { | ||
+ | $this->_type = $config['type']; | ||
+ | } | ||
− | + | // Load the language files if needed. | |
− | + | if ($this->autoloadLanguage) | |
− | + | { | |
− | + | $this->loadLanguage(); | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | / | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | if | ||
− | |||
− | |||
− | |||
} | } | ||
+ | |||
+ | parent::__construct($subject); | ||
} | } | ||
}</source> | }</source> | ||
Line 97: | Line 103: | ||
class ExamplePlugin extends JPlugin | class ExamplePlugin extends JPlugin | ||
{ | { | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
/** | /** | ||
* This method handles the onIncrement event. It takes an integer input and | * This method handles the onIncrement event. It takes an integer input and | ||
* increments its value. | * increments its value. | ||
− | * | + | * |
+ | * @param integer $input An integer to increment | ||
+ | * | ||
+ | * @return integer Incremented integer | ||
+ | * | ||
+ | * @since 1.1 | ||
* @access public | * @access public | ||
− | |||
− | |||
− | |||
*/ | */ | ||
function onIncrement($input) | function onIncrement($input) |
Revision as of 21:14, 24 August 2013
This article is tagged because it NEEDS TECHNICAL REVIEW. You can help the Joomla! Documentation Wiki by contributing to it.
More pages that need help similar to this one are here. NOTE-If you feel the need is satistified, please remove this notice.
Reason: This is way more out of date than I thought :( - going to need serious work
Joomla! 1.5 introduced the JPlugin
class. In the effort to move Joomla! toward a more efficient object-oriented framework, a new plugin system has been developed which follows the Observer pattern. Plugins are observer classes that attach to a global event dispatcher object in the Joomla! core. What does this mean in English? It means that either the Joomla! core or a third party component or module can trigger an event which causes one or more plugins to execute some code.
Implementation[edit]
The implementation of the plugin system is that of an observer pattern. It has two parts, an observer class, JPlugin
, and an observable class, JEventDispatcher
(changed to JEventDispatcher
in ).
/**
* JPlugin Class
*
* @package Joomla.Platform
* @subpackage Plugin
* @since 11.1
*/
class JPlugin extends JEvent
{
/**
* Constructor
*
* @param object &$subject The object to observe
* @param array $config An optional associative array of configuration settings.
* Recognized key values include 'name', 'group', 'params', 'language'
* (this list is not meant to be comprehensive).
*
* @since 11.1
*/
public function __construct(&$subject, $config = array())
{
// Get the parameters.
if (isset($config['params']))
{
if ($config['params'] instanceof JRegistry)
{
$this->params = $config['params'];
}
else
{
$this->params = new JRegistry;
$this->params->loadString($config['params']);
}
}
// Get the plugin name.
if (isset($config['name']))
{
$this->_name = $config['name'];
}
// Get the plugin type.
if (isset($config['type']))
{
$this->_type = $config['type'];
}
// Load the language files if needed.
if ($this->autoloadLanguage)
{
$this->loadLanguage();
}
parent::__construct($subject);
}
}
There are two important things that makes this class work.
One is the constructor which actually gets executed by the parent class of this class JObserver
. The following is what happens in the constructor:
// Register the observer ($this) so we can be notified
$subject->attach($this);
// Set the subject to observe
$this->_subject = &$subject;
This attaches the JPlugin
to an observable object. In the case of plugins, they observe the JEventDispatcher
object.
The second important thing to note is the update method. The update method is passed an array from its trigger. The array contains two elements - the event and the arguments. Once the update method receives this array it extracts the event and removes it from the arguments. It then calls a method of name ‘event’ (passing the arguments array) and returns its response.
Third Party Usage[edit]
<?php
/**
* @version $Id: $
* @package
* @subpackage
* @copyright
* @license
*/
jimport('joomla.plugin');
/**
* Example Plugin
*
* @author
* @package
* @subpackage
* @since
*/
class ExamplePlugin extends JPlugin
{
/**
* This method handles the onIncrement event. It takes an integer input and
* increments its value.
*
* @param integer $input An integer to increment
*
* @return integer Incremented integer
*
* @since 1.1
* @access public
*/
function onIncrement($input)
{
return $input++;
}
}
?>
As you can see, it is quite simple to create a JPlugin
. It is truly as simple as creating a class that extends JPlugin
and writing a method for each event you want the plugin to handle.