Actions

J1.5

Difference between revisions of "Creating a Plugin for Joomla"

From Joomla! Documentation

(Creating the Plugin)
(Edited the text for clarity. Reordered some text.)
Line 1: Line 1:
====== Creating a Plugin for Joomla! 1.5 ======
+
The plugin structure for Joomla! 1.5 is 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.
 
+
===== How to create your own plugin =====
+
  
 
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.
 
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 ====
+
=== Creating the Installation File ===
 
+
 
As with all add-ons 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 searchbot plugin.
 
As with all add-ons 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 searchbot plugin.
 
+
<source lang="php">
 
+
<?xml version="1.0" encoding="iso-8859-1"?>
<source lang="php"><?xml version="1.0" encoding="iso-8859-1"?>
+
 
<install version="1.5" type="plugin" group="search">
 
<install version="1.5" type="plugin" group="search">
    <name>Categories searchbot</name>
+
  <name>Categories searchbot</name>
    <author>Joomla! Project</author>
+
  <author>Joomla! Project</author>
    <creationDate>November 2005</creationDate>
+
  <creationDate>November 2005</creationDate>
    <copyright>(C) 2005 Open Source Matters. All rights reserved.</copyright>
+
  <copyright>(C) 2005 Open Source Matters. All rights reserved.</copyright>
    <license>GNU/GPL</license>
+
  <license>GNU/GPL</license>
    <authorEmail>admin@joomla.org</authorEmail>
+
  <authorEmail>admin@joomla.org</authorEmail>
    <authorUrl>www.joomla.org</authorUrl>
+
  <authorUrl>www.joomla.org</authorUrl>
    <version>1.1</version>
+
  <version>1.1</version>
    <description>Allows searching of Categories information</description>
+
  <description>Allows searching of Categories information</description>
    <files>
+
  <files>
        <filename plugin="categories.searchbot">categories.searchbot.php</filename>
+
      <filename plugin="categories.searchbot">categories.searchbot.php</filename>
    </files>
+
  </files>
    <params>
+
  <params>
        <param name="search_limit" type="text" size="5" default="50" label="Search Limit" description="Number of search items to return"/>         
+
      <param name="search_limit" type="text" size="5" default="50" label="Search Limit" description="Number of search items to return"/>         
    </params>
+
  </params>
</install></source>
+
</install>
 +
</source>
  
 
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.
 
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.
Line 35: Line 32:
 
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.
 
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 parameter '''''method="upgrade"''''' to the tag '''install''', this plugin can be installed without deinstalling it before.
+
'''Tip''' If you add the parameter ''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.
All existing files will be overridden, but old files will not be deleted!
+
So handle with care.
+
 
+
==== Creating the Plugin ====
+
  
 +
=== Creating the Plugin ===
 
Joomla! 1.5 introduces a new, more object-orientated, way of writing plugins. The old method is still supported for backwards-compatibility (see next section).
 
Joomla! 1.5 introduces a new, more object-orientated, way of writing plugins. The old method is still supported for backwards-compatibility (see next section).
 
+
<source lang="php">
 
+
<?php
<source lang="php"><?php
+
 
// no direct access
 
// no direct access
 
defined( '_JEXEC' ) or die( 'Restricted access' );
 
defined( '_JEXEC' ) or die( 'Restricted access' );
Line 53: Line 46:
 
class plg<PluginGroup><PluginName> extends JPlugin
 
class plg<PluginGroup><PluginName> extends JPlugin
 
{
 
{
  /**
+
/**
    * Constructor
+
* Constructor
    *
+
*
    * For php4 compatability we must not use the __constructor as a constructor for
+
* For php4 compatability we must not use the __constructor as a constructor for
    * plugins because func_get_args ( void ) returns a copy of all passed arguments
+
* plugins because func_get_args ( void ) returns a copy of all passed arguments
    * NOT references.  This causes problems with cross-referencing necessary for the
+
* NOT references.  This causes problems with cross-referencing necessary for the
    * observer design pattern.
+
* observer design pattern.
    */
+
*/
    function plg<PluginGroup><PluginName>( &$subject )
+
function plg<PluginGroup><PluginName>( &$subject )
    {
+
{
            parent::__construct( $subject );
+
    parent::__construct( $subject );
  
            // load plugin parameters
+
    // load plugin parameters
            $this->_plugin = JPluginHelper::getPlugin( '<GroupName>', '<PluginName>' );
+
    $this->_plugin = JPluginHelper::getPlugin( '<GroupName>', '<PluginName>' );
            $this->_params = new JParameter( $this->_plugin->params );
+
    $this->_params = new JParameter( $this->_plugin->params );
    }
+
}
 
+
/**
    /**
+
* Plugin method with the same name as the event will be called automatically.
    * Plugin method with the same name as the event will be called automatically.
+
*/
    */
+
function <EventName>()
    function <EventName>()
+
{
    {
+
    $app = &JFactory::getApplication();
        $app = &JFactory::getApplication();
+
  
 
         // Plugin code goes here.
 
         // Plugin code goes here.
 
+
    return true;
        return true;
+
}
    }
+
 
+
 
}
 
}
?></source>
+
?>
 
+
</source>
==== Creating the Plugin (Legacy Mode) ====
+
  
This section describes the legacy method of creating plugins used prior to Joomla! 1.5. Some core Joomla! plugins may still use this method but will be gradually re-written over time. This method is still supported for backwards-compatibility.
+
=== Creating the Plugin (Legacy Mode) ===
 +
This section describes the legacy method of creating plugins used prior to Joomla! 1.5. Some core Joomla! plugins may still use this method but will be eventually rewritten. This method is still supported for backwards-compatibility.
  
 
The code that you want executed when the event triggers is written as a PHP function. Prior to the function definition you make a call to the registerEvent() method so that the Joomla! event system associates your function with the appropriate event.
 
The code that you want executed when the event triggers is written as a PHP function. Prior to the function definition you make a call to the registerEvent() method so that the Joomla! event system associates your function with the appropriate event.
  
 
For example, take a look at this skeleton code:
 
For example, take a look at this skeleton code:
 
+
<source lang="php">
 
+
<?php
<source lang="php"><?php
+
 
// no direct access
 
// no direct access
 
defined( '_JEXEC' ) or die( 'Restricted access' );
 
defined( '_JEXEC' ) or die( 'Restricted access' );
Line 102: Line 91:
 
function <FunctionName>( <ParameterList> ) {
 
function <FunctionName>( <ParameterList> ) {
  
    //Plugin code goes here
+
  // Plugin code goes here
  
 
}
 
}
?></source>
+
?>
 +
</source>
  
With the function $mainframe→registerEvent() your plugin is registered into the Joomla! event system. This means that when the event called '<EventName>' is later triggered, the function called '<FunctionName>' will be called.
+
With the function ''$mainframe→registerEvent()'' your plugin is registered with the Joomla! event system. When the event called ''<EventName>'' is triggered, the function ''<FunctionName>'' will be called.
  
Now you can write your plugin function code anyway you want. If you want to use parameters, it's no problem, just use them as usual. You can register as many events and plugin functions together in one file as you want. When you're done, your plugin is ready for use.
+
Now you can write your plugin function code anyway you want. If you want to use parameters, it's no problem; just use them as usual. You can register as many events and plugin functions in one file as you want.
  
==== Using Plugins in Your Code ====
+
=== 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.
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 which case you don't need to do the following.
+
  
 
If you want to trigger an event then you use code like this:
 
If you want to trigger an event then you use code like this:
 
+
<source lang="php">
 
+
$results = $mainframe->triggerEvent( '<EventName>', <ParameterArray> );
<source lang="php">$results = $mainframe->triggerEvent( '<EventName>', <ParameterArray> );</source>
+
</source>
 
+
  
 
or in Joomla 1.5 fashion:
 
or in Joomla 1.5 fashion:
 
+
<source lang="php">
 
+
$dispatcher =& JDispatcher::getInstance(); $results = $dispatcher->trigger( '<EventName>', <ParameterArray> );
<source lang="php">$dispatcher =& JDispatcher::getInstance(); $results = $dispatcher->trigger( '<EventName>', <ParameterArray> );</source>
+
</source>
 
+
  
 
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).
 
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.
If you are creating a plugin for a new, non-core event, it is also important to remember to activate your plugin after you installed it, and of course to precede any reference to your new plugin with the JPluginHelper::importPlugin() command.
+
 
+
 
+
===== Conclusion =====
+
 
+
The plugin structure for Joomla! 1.5 is 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.
+

Revision as of 16:55, 27 December 2010

Replacement filing cabinet.png
This Namespace has been archived - Please Do Not Edit or Create Pages in this namespace. Pages contain information for a Joomla! version which is no longer supported. It exists only as a historical reference, will not be improved and its content may be incomplete.

The plugin structure for Joomla! 1.5 is 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.

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.

Contents

Creating the Installation File

As with all add-ons 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 searchbot plugin.

<?xml version="1.0" encoding="iso-8859-1"?>
<install version="1.5" type="plugin" group="search">
   <name>Categories searchbot</name>
   <author>Joomla! Project</author>
   <creationDate>November 2005</creationDate>
   <copyright>(C) 2005 Open Source Matters. All rights reserved.</copyright>
   <license>GNU/GPL</license>
   <authorEmail>admin@joomla.org</authorEmail>
   <authorUrl>www.joomla.org</authorUrl>
   <version>1.1</version>
   <description>Allows searching of Categories information</description>
   <files>
       <filename plugin="categories.searchbot">categories.searchbot.php</filename>
   </files>
   <params>
       <param name="search_limit" type="text" size="5" default="50" label="Search Limit" description="Number of search items to return"/>        
   </params>
</install>

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" tag 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 Tutorial:Creating Plugins 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 parameter 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

Joomla! 1.5 introduces a new, more object-orientated, way of writing plugins. The old method is still supported for backwards-compatibility (see next section).

<?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );
 
// Import library dependencies
jimport('joomla.plugin.plugin');
 
class plg<PluginGroup><PluginName> extends JPlugin
{
/**
 * Constructor
 *
 * For php4 compatability we must not use the __constructor as a constructor for
 * plugins because func_get_args ( void ) returns a copy of all passed arguments
 * NOT references.  This causes problems with cross-referencing necessary for the
 * observer design pattern.
 */
 function plg<PluginGroup><PluginName>( &$subject )
 {
    parent::__construct( $subject );
 
    // load plugin parameters
    $this->_plugin = JPluginHelper::getPlugin( '<GroupName>', '<PluginName>' );
    $this->_params = new JParameter( $this->_plugin->params );
 }
/**
 * Plugin method with the same name as the event will be called automatically.
 */
 function <EventName>()
 {
    $app = &JFactory::getApplication();
 
        // Plugin code goes here.
    return true;
 }
}
?>

Creating the Plugin (Legacy Mode)

This section describes the legacy method of creating plugins used prior to Joomla! 1.5. Some core Joomla! plugins may still use this method but will be eventually rewritten. This method is still supported for backwards-compatibility.

The code that you want executed when the event triggers is written as a PHP function. Prior to the function definition you make a call to the registerEvent() method so that the Joomla! event system associates your function with the appropriate event.

For example, take a look at this skeleton code:

<?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );
 
$mainframe->registerEvent( '<EventName>', '<FunctionName>' );
 
function <FunctionName>( <ParameterList> ) {
 
  // Plugin code goes here
 
}
?>

With the function $mainframe→registerEvent() your plugin is registered with the Joomla! event system. When the event called <EventName> is triggered, the function <FunctionName> will be called.

Now you can write your plugin function code anyway you want. If you want to use parameters, it's no problem; just use them as usual. You can register as many events and plugin functions in one file as you want.

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:

$results = $mainframe->triggerEvent( '<EventName>', <ParameterArray> );

or in Joomla 1.5 fashion:

$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.