Event listeners

The events and event listeners are the backbone of PushJS.
Listening on channels for certain events is the core business (and the most fun thing to do)

System events and custom events

PushJS is distinguishing between system events and custom events.

System events can only come from PushJS self and have the purpose of notifying the application of important events
happening within your application. This could be a client entering or leaving the channel. Or when a client has an
updated attribute. Read more about client attributes. When a system event is dispatched only the client object is sent as parameter to your defined callback function.

Custom events are created and dispatched by your application code. They work the same as a system event, the only difference
is that the callback function does not get a client object but an event object. Which contains the methods
for fetching the client who triggered the event and the data that has been sent with the event.

Attach a system event listener

Once the ready event has been fired you are all set to attach event listeners.
The following code snippet assumes you have the ready function attached as callback when PushJS loaded.
It demonstrates how to attach an event listener for a system event CLIENT_ENTER. The client will now get notified of every new client that enters the channel

                
<script>

    function ready() {

        // i wonder what we can see here
        var channelId = "RICK_ROLLIN_CHANNEL";

        // create and join the channel
        PushJS.channelManager.createChannel(channelId);
        PushJS.channelManager.joinChannel(channelId);

        PushJS.channelManager.addEventListener(channelId, PushJS.events.CLIENT_ENTER, onClientEnter);
    }

    function onClientEnter(client) {
        console.log('A new rick has joined the channel!');
    }

</script>
                
            

If you take a look at the code snippet above, two things are happening.

  1. The ready event is fired and the callback to the "ready" function is being made
  2. In the ready function, a new event listener is defined which accepts 2 parameters: an event and a callback function
This particular event listener is listening to a system event. System events are predefined events and are further discussed in system events.
The onClientEnter function will now be used as a callback everytime a new client connects or reconnects to your channel.
Read more about channels here.

Custom event listeners

                
<script>

    function ready() {


        // i wonder what we can see here
        var channelId = "RICK_ROLLIN_CHANNEL";

        // create and join the channel
        PushJS.channelManager.createChannel(channelId);
        PushJS.channelManager.joinChannel(channelId);

        // when PushJS is loaded, attach an event listener that
        // is defined with a custom event and callback function
        PushJS.channelManager.addEventListener(channelId, 'RICK_ROLLED_EVENT', onRickRollEvent);
    }

    function onRickRollEvent(fromClient, message) {

        // When the event is received, the callback receives 2 arguments:
        // the client and the message that was send.
        console.log(message);
    }

    function doSomethingAwesome() {

        // The dispatchEvent method takes 2 parameters.
        // Event name and a string. The string could be a simple message
        // or a stringified JSON object.
        PushJS.eventManager.dispatchEvent("RICK_ROLLED_EVENT", JSON.stringify({
            give_you_up: "never"
        }));
    }

</script>
                
            

In the above snippet, in the ready function, a new event listener is defined with the callback function `OnMyEvent`.
This listener will wait for an incoming event MY_EVENT.

In the same snippet there is also a function called doSomethingAwesome. If this function is called, it will dispatch the event `MY_EVENT`.
All clients that are subscribed to `RICK_ROLLED_EVENT` will trigger the callback function `onRickRollEvent`.