L'objet jEvent sert à la fois d'émetteur d'événement, et en même temps de conteneur des réponses.

Pour émettre un événement, il faut utiliser la méthode statique notify().

Elle accepte en paramètre un nom d'évènement (qui n'est constitué que de caractères alphanumériques), et un tableau facultatif de paramètres (à utiliser selon l'évènement).

Vous recevez en retour l'objet jEvent instancié pour l'occasion, et contenant les réponses (ne pas confondre avec les objets jResponse, utilisés dans les contrôleurs). Les réponses sont un ensemble de valeurs dont la structure et le nombre dépend de l'événement et du nombre de modules ayant répondu.

   //exemple avec paramètre
   $eventParams = array('user' => $userObject);
   $theEvent = jEvent::notify('authCanLogin', $eventParams);
 
   //exemple sans paramètres
   $theEvent = jEvent::notify('authCanLogin2');

Pour accéder aux données des réponses retournés par les listeners des modules, il faut utiliser la méthode getResponse de l'objet jEvent qui a été retourné par notify:

  $reponses = $theEvent->getResponse();

Le résultat est un tableau des données que chaque module à renvoyé.

Vous avez d'autres méthodes pour manipuler les données retournées :

• inResponse($responseKey, $value) : indique si il existe une clé avec la valeur donnée dans les données retournées.
• getResponseByKey($responseKey) : renvoi la liste des données qui correspondent à la clé donnée (renvoi null si il n'y a aucune donnée avec cette clé)
• allResponsesByKeyAreTrue($responseKey) : indique si toutes les données avec la clé donnée ont la valeur true.
• allResponsesByKeyAreFalse($responseKey) : indique si toutes les données avec la clé donnée ont la valeur false.

Il n'y a pas de listener par défaut dans les modules. Aussi, pour qu'un module puisse répondre à un événement, il faut en créer un, et le déclarer dans le fichier events.xml du module. Il n'y a pas de limite du nombre de listener.

Il y a deux choses à faire pour un listener : le créer, puis le déclarer.

créer le listener ¶

class authListener extends jEventListener {

   function onAuthCanLogin ($event) {

        // recupération d'un paramètre de l'événment
        $user = $event->getParam('user');

        // traitement
        $ok = true;
        if (isset($user->actif)) {
            $ok = ($user->actif == '1');
        }

        $ok = $ok && ($user->password != '');

        // renvoi de donnée en réponse
        $event->add(array('canlogin'=>$ok));
   }
}

class authListener extends jEventListener {

    protected $eventMapping = array(
      'foo.bar' => 'execFooBar'
    );

    function execFooBar ($event) {
        // here process the event.
    }
}

Déclarer le listener ¶

<events xmlns="http://jelix.org/ns/events/1.0">
   <listener name="auth">
       <event name="AuthCanLogin" />
   </listener>
</events>

Il peut arriver que vous vouliez désactiver un listener fourni par un module tiers, pour un tas de raison.

Cela est possible en les indiquant dans la section [disabledListeners] de la configuration principale. Les clés sont les noms d'évènements, les valeurs sont les sélecteurs des listeners.

[disabledListeners]
authLogin="aModule~theListener"

Dans cet example, le listener theListener du module "aModule" ne sera pas appelé quand l'évènement authLogin sera émis.

Si vous voulez désactiver plusieurs listener pour un même évènement, utilisez simplement la notation [] pour indiquer un tableau :

[disabledListeners]
authLogin[]="aModule~theListener"
authLogin[]="otherModule~otherListener"