Publishing and Subscribing to Custom Events

Clicking in the grey box resizes the blue <div> within it. A Custom Event is fired which publishes the blue box's new size. One subscriber to that Custom Event looks at the new width and resizes the brown box to match. A second subscriber looks at the blue <div>'s new height and resizes the red box to match.

Click anywhere within the grey box to resize me.
Width will resize to match blue box.
Height will resize to match blue box.

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 the resizer's width.


Our click handler, to be fired when the grey container <div> is clicked on, 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 the 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 the 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 a functions that to respond and react to this change. We've specified that we'll have one function that will pay attention to onSizeChange, get its width, 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 our handlers receive. That 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.