Un listener est une classe stockée dans classes avec un nom spécifique.

Depuis Jelix 1.8.1, cela peut être une classe stockée n'importe où, avec n'importe quel nom, et qui doit être auto-chargeable. Ce qui est beaucoup moins contraignant.

Pour créer un listener dans classes, il faut d'abord lui donner un nom logique. Nous allons utiliser "auth" par exemple. Ensuite il faut créer une classe pour le listener. Son nom est une concatenation du nom logique avec "Listener". Stocker cette classe dans un fichier qui a pour nom nomlogique.listener.php, et donc auth.listener.php pour notre exemple, ce fichier devant être dans le dossier classes du module.

Une classe de listener doit hériter de jEventListener et doit contenir une méthode pour chaque évènement auquel le listener répond. Ces noms de méthodes commencent par on suivi du nom d'événement. Et ces méthodes prennent en paramètre l'objet jEvent correspondant à l'événement. Exemple :

class authListener extends jEventListener {
// ou
// class \MyModule\Listeners\Auth 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));
   }
}

Ce listener répond à l'évènement "AuthCanLogin". La méthode récupère le paramètre 'user' de l'évènement. Et ajoute une donnée dans la réponse avec la méthode add. Ce paramètre et cette donnée de réponse dépendent uniquement de l'évènement AuthCanLogin. Pour d'autres évènements, il peut y avoir plusieurs paramètres ou aucun, d'autres types de données de réponses ou aucune réponse.

Pour les évènements dont le nom ne peut correspondre à un nom de méthode, comme un nom comportant des points (ex: foo.bar), vous pouvez indiquer quelle méthode il faut exécuter, dans une propriété eventMapping. Les clés sont les noms d'évènements, les valeurs les noms des méthodes.

class authListener extends jEventListener {

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

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

Note : vous pouvez changer la façon dont votre listener traite les évènements (nom des méthodes correspondantes aux évènements etc), en redéfinissant la méthode performEvent() du listener.

il faut ensuite déclarer le listener. Cela se fait dans un fichier events.xml placé à la racine du module. Voici un exemple :

<events xmlns="http://jelix.org/ns/events/1.0">
   <listener name="auth">
       <event name="AuthCanLogin" />
   </listener>
   <!-- or -->
   <listener name="\MyModule\Listeners\Auth">
       <event name="AuthCanLogin" />
   </listener>
</events>

L'attribute name de la balise listener doit contenir le nom logique du listener, si sa classe est stockée dans classes/, ou le nom entier de la classe si elle est auto-chargeable.

Vous pouvez déclarer autant de listener que vous voulez grâce à la balise <listener>. Et dans chacune d'elles vous indiquez tous les évènements que prend en charge le listener, grâce à des balises <event>.