Using Custom Events

Custom Events, part of the YUI Event Utility, are special developer-created events that express the occurance of and information about interesting moments taking place on a page. Custom Events can be subscribed to by any script on the page; the publisher of the Custom Event knows nothing about the subscribers, and individual subscribers don't need to know anything about each other.

To illustrate the use of Custom Event, we'll create a single <div> called resizer that resizes itself when its container is clicked. When we resize this <div> we'll publish a Custom Event, onSizeChange, that reports the new height and width of our resizer. We will have two modules that subscribe to this information; the first will respond by changing its height to remain the same as the resizer's height and the second will change its width.

Start with some simple CSS rules and markup for the appearing elements:

Next, we'll compose our script. We begin by creating our Custom Event instance. We'll fire() this Custom Event — that is, call its fire method — when our click handler executes and changes resizer's width.

Our click handler, to be fired when the grey container <div> is clicked, performs a number of housekeeping tasks like figuring out the new size of the resizer element, making sure that a minimum size is maintained, etc. Note that it only fires the Custom Event if the click will result in a sane value for resizer's height or width. Line 35 below is where we ultimately fire the Custom Event. We pass in the new height and width of resizer as an argument when we fire the Custom Event because we want our subscribers to have access to that information.

We now have a Custom Event and we're firing it at the right time, passing in the relevant data payload. The next step is to create functions that respond and react to this change. We've specified that we'll have one function that will pay attention to our onSizeChange Custom Event, get the new width of resizer, and change the width of the brown box to match; another function will do the same for the red box's height. Note that the argument we passed in when we fired the Custom Event (an object literal: {width: x, height: y}) is available to us in the second argument received by our handlers. That second argument is an array, and our object is the first item in the array.

The final step in this example is to subscribe our Custom Event handlers to the onSizeChange Custom Event we created in the first script step. We do this by calling onSizeChange's subscribe method and passing in the functions we want to subscribe:

This is a simple example of how to use Custom Events. One of the powerful things about this concept is how far it can extend — we only have two subscribers in this example, but we could have from zero to n subscribers. Custom Events give you granular control over scope and firing order and are an excellent way to provide inter-module messaging within your application.

Configuration for This Example

You can load the necessary JavaScript and CSS for this example from Yahoo's servers. Click here to load the YUI Dependency Configurator with all of this example's dependencies preconfigured.