First, choose a name. We will use 'auth' as an example. Then create a listener class. Note that the class name is a concatenation of the name and of 'Listener', so in our case, 'authListener'. Put that class in a file called {name}.listener.php, so auth.listener.php for us, in the classes folder of your module. Remember, your listener class must inherit from jEventListener.

The listener 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:

//file auth.listener.php

class authListener 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">
   <!-- We have 2 listeners each listening for some events. However, both of them will respond to the AuthCanViewUser event. -->
   <listener name="auth">
       <event name="AuthCanLogin" />
       <event name="AuthCanViewUser" />
   </listener>
   <listener name="auth2">
       <event name="AuthCanLogin2" />
       <event name="AuthCanViewUser" />
   </listener>
</events>

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.