A listener is a class stored into the classes folder with a specific name.

Since Jelix 1.8.1, it could be any classes that is autoloadable, without specific name. It is more flexible.

To create a listener stored into the classes folder, first choose a "logical" name. We will use 'auth' as an example. Then create a listener class with the name that is a concatenation of the "logical" name with the name 'Listener', so in our case, authListener. Put that class in a file called {logicalname}.listener.php, so auth.listener.php for us, in the classes folder of your module.

A listener class must inherit from jEventListener and it needs to implement one method for each event it is supposed to respond to. Those methods should follow this convention : on following by the event name. They need to accept as single argument a jEvent object.

Example:

class authListener extends jEventListener {
// or
// class \MyModule\Listeners\Auth extends \jEventListener {

   function onAuthCanLogin ($event) {
        //retrive user parameter
        $user = $event->getParam('user');

        //the actual processing
        $ok = true;
        if (isset($user->active)) {
            $ok = ($user->active == '1');
        }
        $ok = $ok && ($user->password != '');

        //the response
        $event->add(array('canlogin'=>$ok));
   }
}

This example demonstrates a listener responding to the AuthCanLogin event. First, the onAuthCanLogin method retrieves an 'user' parameter from the event object. Next, it does it's internal processing, and finally, it adds some data to the response by calling $event->add.

For events having a name that cannot be a method name, like name including characters like a dot, you can indicate the method to execute into a property eventMapping. Keys are event names, values are method names.

class authListener extends jEventListener {

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

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

Note: the convention of the name of methods and the calling of methods corresponding to events can be changed by redefining the method performEvent of your listener.

The final step to setup a listener is to declare it. This is done through the events.xml file located in your module root folder. For example:

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

The name attribute of the listener element must indicate the "logical" name of the listener, if it is stored into classes, or the full qualified name of the class, if it is an autoloadable class.

A listener can listen to more than one event. Since it would take too much resources to load all the listeners one by one and check what events do they respond to, you also need to list all the events that you want a listener to listen to. Remember that two listener can also respond to the same event, and that there isn't a conventional structure for the responses.