Actions

Difference between revisions of "Plugin Developer Overview"

From Joomla! Documentation

(New page: {{RightTOC}} Category:Development Category:Framework Category:Plugins == Overview == New in Joomla! 1.5 is a <code>JPlugin</code> class. In the effort to move Joomla! toward ...)
 
(Update to 3.x)
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{RightTOC}}
+
{{version|2.5,3.x}}
[[Category:Development]]
+
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.  
[[Category:Framework]]
+
[[Category:Plugins]]
+
 
+
== Overview ==
+
 
+
New in Joomla! 1.5 is a <code>JPlugin</code> class. In the effort to move Joomla! toward a more efficient object-oriented framework a new plugin system has been developed. 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. Isn’t this the same as a mambot? No, not exactly. It is similar in basic principle in that both a plugin and a mambot are triggered by an event and both execute code. One issue with a mambot is that it requires its functions to be declared in a global scope. Since a JPlugin is a class, the methods that handle the events can share variables and have private helper methods as well, which makes for a much cleaner system for handling events.  
+
  
 
== Implementation ==
 
== Implementation ==
  
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>.
+
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}}).
  
<pre>/**
+
<source lang="php">
 +
/**
 
  * JPlugin Class
 
  * JPlugin Class
 
  *
 
  *
  * @package Joomla.Framework
+
  * @package     Joomla.Platform
  * @subpackage Application
+
  * @subpackage Plugin
  * @since 1.5
+
  * @since       11.1
 
  */
 
  */
class JPlugin extends JObserver
+
class JPlugin extends JEvent
 
{
 
{
 
/**
 
/**
 
* Constructor
 
* Constructor
*  
+
*
* For php4 compatability we must not use the __constructor as a constructor for plugins
+
* @param  object  &$subject  The object to observe
* because func_get_args ( void ) returns a copy of all passed arguments NOT references.
+
* @param  array  $config    An optional associative array of configuration settings.
* This causes problems with cross-referencing necessary for the observer design pattern.
+
*                             Recognized key values include 'name', 'group', 'params', 'language'
*  
+
*                             (this list is not meant to be comprehensive).
* @param object $subject The object to observe
+
*
* @since 1.5
+
* @since   11.1
 
*/
 
*/
function JPlugin(& $subject)
+
public function __construct(&$subject, $config = array())
 
{
 
{
parent::__construct($subject);
+
// 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.
* Method to map events to handler methods
+
if (isset($config['name']))
*
+
{
* @access public
+
$this->_name = $config['name'];
* @param array Arguments
+
* @return mixed Routine return value
+
* @since 1.1
+
*/
+
function update( &$args )
+
{
+
/*
+
* First lets get the event from the argument array. Next we will unset the
+
* event argument as it has no bearing on the method to handle the event.
+
*/
+
$event = $args['event'];
+
unset($args['event']);
+
+
/*
+
* If the method to handle an event exists, call it and return its return
+
* value.  If it does not exist, return a boolean true.
+
*/
+
if (method_exists($this, $event)) {
+
return call_user_func_array(array($this, $event), $args);
+
} else {
+
return true;
+
 
}
 
}
 +
 +
// Get the plugin type.
 +
if (isset($config['type']))
 +
{
 +
$this->_type = $config['type'];
 +
}
 +
 +
// Load the language files if needed. Note whilst this method is in the
 +
// JPlugin class it has been left out of the docs for code clarity.
 +
if ($this->autoloadLanguage)
 +
{
 +
$this->loadLanguage();
 +
}
 +
 +
parent::__construct($subject);
 
}
 
}
}</pre>
+
}</source>
  
 
There are two important things that makes this class work.
 
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 <code>JObserver</code>. The following is what happens in the constructor:
+
One is the constructor which actually gets executed by the parent class of this class <code>JEvent</code>. The following is what happens in the constructor:
  
<pre>// Register the observer ($this) so we can be notified
+
<source lang="php">// Register the observer ($this) so we can be notified
 
$subject->attach($this);
 
$subject->attach($this);
  
 
// Set the subject to observe
 
// Set the subject to observe
$this->_subject = &$subject;</pre>
+
$this->_subject = &$subject;</source>
  
 
This attaches the <code>JPlugin</code> to an observable object. In the case of plugins, they observe the <code>JEventDispatcher</code> object.
 
This attaches the <code>JPlugin</code> to an observable object. In the case of plugins, they observe the <code>JEventDispatcher</code> 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.
+
The second important thing to note is the update method in the <code>JEvent</code> class. 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 ==
 
== Third Party Usage ==
  
<pre><?php
+
<source lang="php"><?php
 
/**
 
/**
 
  * @version $Id: $
 
  * @version $Id: $
Line 104: Line 104:
 
{
 
{
 
/**
 
/**
* Constructor
+
* This method handles the onIncrement fictional event.  It takes an integer input and  
*
+
* @param object $subject The object to observe
+
* @since 1.1
+
*/
+
function ExamplePlugin( &$subject ) {
+
parent::__construct( $subject );
+
}
+
 
+
/**
+
* 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 3.x
 
* @access public
 
* @access public
* @param int $input An integer to increment
 
* @return int Incremented integer
 
* @since 1.1
 
 
*/
 
*/
 
function onIncrement($input)
 
function onIncrement($input)
Line 127: Line 119:
 
}
 
}
 
}
 
}
?></pre>
+
?></source>
  
 
As you can see, it is quite simple to create a <code>JPlugin</code>. It is truly as simple as creating a class that extends <code>JPlugin</code> and writing a method for each event you want the plugin to handle.
 
As you can see, it is quite simple to create a <code>JPlugin</code>. It is truly as simple as creating a class that extends <code>JPlugin</code> and writing a method for each event you want the plugin to handle.
 +
<noinclude>[[Category:Plugin Development|Overview]][[Category:Framework]]</noinclude>

Revision as of 21:20, 24 August 2013

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

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 Joomla 3.x).

/**
 * 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. Note whilst this method is in the
                // JPlugin class it has been left out of the docs for code clarity.
                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 JEvent. 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 in the JEvent class. 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

<?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 fictional event.  It takes an integer input and 
         * increments its value.
         *
         * @param  integer  $input An integer to increment
         *
         * @return integer  Incremented integer
         *
         * @since 3.x
         * @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.