Joomla! Documentation™

Note sur la version : Bien que ce document concerne Joomla ! 2.5 et 3.x, JEventDispatcher n'existe pas dans Joomla 2.5. Dans ce cas, remplacez JEventDispatcher par JDispatcher. L'utilisation de JDispatcher est possible dans Joomla 3.x mais générera un avis de dépréciation.

Le système d'événements de Joomla ! permet une méthode flexible pour les composants, modules et plug-ins de communiquer avec d'autres plug-ins en suivant le Modèle d'observateur. Ce modèle est plus facilement décrit comme un simple mécanisme de communication. Le principe de base est que zéro ou plusieurs "observateurs" ou "auditeurs" s'enregistrent auprès du système pour un événement déterminé et connu. À un moment précis du cycle de vie d'une application, le "communicateur" (dans notre cas, un composant, un module ou un plug-in) déclenche l'événement et transmet certaines informations à tous les observateurs. Les observateurs peuvent alors agir sur les informations qui leur sont transmises et, éventuellement, renvoyer un résultat au communicateur.

Contexte

Mise en œuvre de Joomla ! Observer

Joomla ! met en œuvre le modèle Observer à un niveau global par le biais du JPlugin (Observer) et du JEventDispatcher Classes (observables). Toute personne souhaitant recevoir une notification d'événements créera un plug-in qui étend la fonction la classe JPlugin. Les sous-classes de JPlugin s'enregistreront automatiquement auprès de la classe globale JEventDispatcher lorsque leur catégorie de plug-in aura été chargée (nous y reviendrons plus tard). La classe JEventDispatcher est utilisée comme mécanisme de distribution qui reçoit les événements des communicateurs et les transmet aux écouteurs qui ont été chargés. Pour une explication complète, il est recommandé de lire [Plugin Developer Overview|la présentation du développeur du plugin].

Pourquoi devenir un communicateur

Il peut y avoir des moments dans le cycle de vie de votre composant où il serait bon d'informer les autres qu'une action a eu lieu. Par exemple, disons que vous avez un composant de bibliothèque de disques compacts (CD). Vous pouvez décider de faire savoir aux autres qu'un nouveau CD a été ajouté à la bibliothèque. Dans ce cas, vous pourriez documenter un événement bien connu (onCdAddedToLibrary par exemple) et au moment opportun, trigger l'événement en transmettant des informations sur le nouveau CD qui a été ajouté à la bibliothèque. Tous les plug-ins qui ont mis en œuvre cet événement seront informés de l'information et pourront la traiter comme bon leur semble. Une communication instantanée !

Mise en œuvre

Comment devenir un communicateur

Comme toute la répartition est gérée par le noyau de Joomla !, il est facile de devenir un communicateur. En fait, il s'agit simplement de charger un certain ensemble de plug-ins et d'appeler la méthode de déclenchement de la classe JEventDispatcher

Vous vous demandez peut-être comment savoir quel ensemble de plug-ins charger. Cela dépend de vous. Les plug-ins sont gérés au niveau d'un groupe qui est défini dans le fichier de déploiement XML du plug-in. Il existe huit groupes de plug-ins prédéfinis et chaque groupe de plug-ins est destiné à gérer un ensemble différent de tâches. Par exemple, il y a un groupe de plug-in de recherche qui est destiné à gérer la recherche et un groupe de plug-in d'utilisateur destiné à gérer les fonctions spécifiques à l'utilisateur telles que l'ajout et la suppression d'un utilisateur du système Joomla ! Ces groupes de plug-ins ne sont chargés que lorsqu'ils sont nécessaires, à savoir par le communicateur. Ainsi, vous pouvez créer votre propre groupe de plug-ins et l'appeler comme vous le souhaitez. Puisque votre composant est bien défini, tous les auditeurs sauront exactement quel groupe de plug-ins et quels événements ils doivent écouter.

Comment déclencher des événements

Cela nous amène à l'essentiel de cet article : comment déclencher des événements pour que les plug-ins de mise en œuvre puissent agir sur eux. La première chose à faire est de charger votre groupe de plug-ins. Cela se fait par le biais du code suivant :

JPluginHelper::importPlugin( 'myplugingroup' );

Cela chargera tous les plug-ins activés qui se sont définis comme faisant partie de votre groupe. La prochaine chose à faire est d'obtenir une instance de la classe JEventDispatcher :

$dispatcher = JEventDispatcher::getInstance();

Vous remarquerez deux choses ici. Premièrement, nous utilisons la méthode getInstance(), et non new, pour créer une nouvelle instance. En effet, nous devons obtenir l'instance singleton globale de l'objet JEventDispatcher qui contient une liste de tous les plug-ins disponibles.

Ensuite, nous devons déclencher notre événement personnalisé :

$results = $dispatcher->trigger( 'onCdAddedToLibrary', array( &$artist, &$title ) );

Ici, nous avons déclenché l'événement onCdAddedToLibrary et transmis le nom de l'artiste et le titre du morceau. Vous pouvez choisir les paramètres que vous passez et leur nombre. Le passage des paramètres par référence (en utilisant un &) permet aux plug-ins de modifier les variables passées. Tous les plug-ins reçoivent ces paramètres, les traitent et renvoient éventuellement des informations. Le code appelant peut accéder aux valeurs retournées via le tableau $results (chaque élément correspond au résultat d'un plugin).

Mises en garde

Vous définissez une API

En proposant des événements auxquels les plugins peuvent répondre, vous créez effectivement une API. Une bonne planification est extrêmement importante ; une fois votre code publié, les autres développeurs commenceront à dépendre des noms et des paramètres de vos événements. Les modifier ultérieurement rompra la compatibilité avec tous les plugins qui les utilisent.

Charger le bon groupe de plugins

Une chose à noter à propos de la méthode de déclenchement est que rien ne définit quel groupe de plug-ins doit être notifié. En réalité, tous les plug-ins qui ont été chargés sont notifiés, quel que soit le groupe dans lequel ils se trouvent. Il est important de s'assurer que le nom de l'événement n'entre pas en conflit avec celui d'un autre groupe de plug-ins. Most of the time this is not an issue because your component is the one that is loading the plug-in group, so you know which ones are loaded. However be aware that the system plug-in group is loaded very close to the beginning of the request. Make sure you don't have any event naming conflicts with the system events. La plupart du temps, ce n'est pas un problème car votre composant est celui qui charge le groupe de plug-ins. pour que vous sachiez lesquels sont chargés. Sachez toutefois que le groupe de plug-ins system est chargé très près du début de la requête. Assurez-vous que vous n'avez pas de conflits de noms d'événements avec les événements système.