Joomla! Documentation™

Joomla! 

3.x

série

La structure d'un plugin pour Jomla! 1.5 était très flexible et puissante. Les plugins peuvent non seulement gérer des événements déclenchés par les applications du noyau et des extensions, mais ils peuvent également être utilisés pour rendre des extensions tierces extensibles et puissantes. Le principal changement entre Joomla! 1.5 et les séries 2.5/3 est une modification au niveau des noms des événements.

Cette procédure devrait vous fournir les éléments de base à connaître pour créer votre propre plugin. La plupart des plugins sont constitués d'un seul fichier de code, mais pour installer correctement le code du plugin, il doit être empaqueté dans un fichier d'installation pour pouvoir être traité par l'installateur de Joomla.

Création du fichier d'installation

Comme avec toutes les extensions de Joomla, les plugins s'installent facilement en tant que fichier .zip (.tar.gz est également pris en charge) ; toutefois, un fichier XML correctement formaté doit être inclus. A titre d'exemple, voici le fichier XML d'installation pour un plugin de recherche de catégories.

<?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>

Comme vous pouvez le constater, le système est similaire aux autres fichiers d'installation XML de Joomla. Regardez l'entrée group="xxx" de la balise <extension> et l'information de la balise <filename>. Ces informations indiquent à Joomla! dans quel dossier copier le fichier et dans quel groupe le plugin doit être ajouté.

Si vous créez un plugin qui répond aux événements existants du noyau, l'attribut groupe="xxx" devra être modifié pour refléter le nom du dossier du plugin existant pour le type d'événement que vous souhaitez augmenter. Par exemple, group="authentication" ou group="user". Consultez Plugin/Events pour voir une liste complète des catégories d'événements du noyau. Lors de la création d'un nouveau plugin pour répondre aux événements du noyau, il est important que le nom de votre plugin soit unique et ne soit pas en conflit avec d'autres plugins qui pourraient également répondre à un événement du noyau dont vous souhaitez également vous servir.

Si vous créez un plugin pour répondre à des évènements système hors noyau, la balise groupe="xxx" doit être différente de toutes les catégories existantes du noyau.

Conseil : si vous ajoutez l'attribut method="upgade" à la balise extension, ce plugin pourra être installé sans avoir à désinstaller une version antérieure. Tous les fichiers existants seront remplacés, mais les anciens fichiers ne seront pas supprimés.

Création du Plugin

La méthode orientée objet de l'écriture de plugins consiste à écrire une sous-classe de JPlugin, une classe de base qui met en œuvre les propriétés de base des plugins. Dans vos méthodes, les propriétés suivantes sont disponibles :

• $this->params: les paramètres définis pour ce plugin par l'administrateur
• $this->_name: le nom du plugin
• $this->_type: le groupe (type) du plugin
• $this->db: l'objet db (depuis )
• $this->app: l'objet application (depuis )

Astuce Pour utiliser $this->db et $this->app, JPlugin teste si la propriété existe et si elle n'est pas privée. S'il est nécessaire d'utiliser ces objets par défaut, créez des propriétés non-instantiées dans la classe du plugin (i.e. protected $db; protected $app; dans la même zone que protected $autoloadLanguage = true;). Les propriétés n'existeront pas à moins de les créer explicitement.

Dans l'exemple de code suivant, <PluginGroup> représente le groupe (type) du plugin et <PluginName> représente son nom. Notez que les noms de classe et de fonction en PHP sont insensibles à la casse.

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

class plg<PluginGroup><PluginName> extends JPlugin
{
	/**
	 * Load the language file on instantiation. Note this is only available in Joomla 3.1 and higher.
	 * If you want to support 3.0 series you must override the constructor
	 *
	 * @var    boolean
	 * @since  3.1
	 */
	protected $autoloadLanguage = true;

	/**
	 * Plugin method with the same name as the event will be called automatically.
	 */
	 function <EventName>()
	 {
		/*
		 * Plugin code goes here.
		 * You can access database and application objects and parameters via $this->db,
		 * $this->app and $this->params respectively
		 */
		return true;
	}
}
?>

Utiliser les plugins dans votre code

Maintenant que vous avez créé votre plugin, vous pourriez souhaiter l'appeler dans votre code. Vous ne devriez pas. Le noyau Joomla! propose déjà un grand nombre d'événements prédéfinis que vous pourrez lier au code de votre plugin. Dans ce cas, vous n'avez pas besoin d'effectuer les opérations suivantes.

Si vous souhaitez déclencher un événement, alors il convient d'utiliser le code comme ceci :

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

Il est important de noter que les paramètres doivent se trouver dans un tableau array. La fonction de plugin elle-même contiendra les paramètres comme des valeurs uniques. La valeur retournée sera composée d'un tableau array de valeurs retournées par les différents plugins (elle peut également contenir des tableaux array multi-niveaux).

Si vous créez un plugin pour un nouvel événement non contenu dans le noyau, n'oubliez pas d'activer votre plugin après son installation. Précéder toute référence à votre nouveau plugin avec la commande JPluginHelper::importPlugin().