jQuery custom events

Its been a while. I guess I still need to get used to publishing the posts and all… 🙂
Anyway, I wanted to publish a few more and then I realized that one subject keeps recurring in almost all of the upcoming posts: custom events. You can and should read all about events in jQuery at http://docs.jquery.com/Events/jQuery.Event.

Custom events go together with an event-driven programming style, a style whose benefits I’m sure are explained by many articles out there. What I want to focus on is the relation to web programing in jQuery or javascript in general. In every application I worked on there was a need to bind to certain events like onclick, onsubmit and onload (to name a few). I don’t think there is a modern application out there that doesn’t use at least one kind of event. Therefore I think it’s only natural that the application will define a few events of its own.

In my opinion, integrating custom events in almost every web application is very beneficial for us as developers, since it gives us some very powerful possibilities and flexibility. Let’s think of a basic example related to gaming; let’s say we’ve created a game with the following basic flow:

  1. When the player’s turn starts a pair of dice is interactive.
  2. The player then rolls the dice.
  3. The player chooses a move.
  4. A piece on the board moves.
  5. We check if there is a win condition.
  6. If there is a win condition, finish the game.
  7. Else, start a new turn.

We’ve described a very basic dice game. I don’t really have any idea what the game is about at this point and for the purpose of our example, it doesn’t even matter. Once we have written the code for this simple interaction we can use it for many different dice games. We can port it from game to game by copy pasting the code we had, or we could use some kind of hooks for the different functionality, like what to do when the turn starts, what to do when the player has made his move, or even when we have a win condition. All of these can be events. A custom event can be “player_rolled_dice”, “player_won”, and so on… an event can receive parameters just like functions, and that is what we are about to see now.
Take the following example:

function checkWin(){
jQuery(document).trigger("player_won", {score: the_score});

We can see the checkWin function, which triggers the event “player_won”. We didn’t see anything binding to this event, so nothing will happen, but let’s say later on we decide that we want to keep a high score board. Because we already have a “hooking” place, we don’t need to change the code for the checkWin function; all we need to do is something like this:

jQuery(document).bind("player_won", saveHighscore);
function saveHighscore(event, params){

To add to more flexibility, this can be in its own file: if the file is loaded / initialized the code will run, the function will be bound to the event, and the highscore will be saved upon win. And if it doesn’t, then nothing will happen. We just expanded our functionality without changing the original code.

I know this is a bit high level with no real practice code, so let’s look at a small example to see how things work.
Create a web page with jQuery attached (or use an existing one) and add the following javascript:

function gotMsg(event, data){
  alert("I got the following message for you: "+data.message)
jQuery(document).bind("got_message", gotMsg);
jQuery(document).trigger("got_message", {message: "testing"});

You can even add another bound function, such as:

function gotMsg2(event, data){
  alert("Did I tell you I got : "+data.message)
jQuery(document).bind("got_message", gotMsg2);

And if you will run the code now you will get two annoying alerts in the order in which you binded the events. The possibilities which this functionality brings us, as we will see in the upcoming posts, are really great.

’till next time,
Adi Gabai

Leave a Reply

Your email address will not be published. Required fields are marked *