Custom Event Example: Simple Publisher and Subscriber

In this YDN-JavaScript post, mattesid requests a simple example of using Custom Event, part of the YUI Event Utility, to respond to changes in the size of a page element.

In this example, we'll have a grey container div within which is a blue resizer div. If you click in container, resizer will automatically resize to "x" position of your click. When this happens, the click hander will fire a Custom Event, onSizeChange, which will let other components on the page know about the change. We'll create one such component, a subscriber, that will write out to the subscriber div the new width of the resizer element.

Start with some simple CSS code for the appearing elements:

<style type="text/css">
#container {width:400px; height:75px; padding:10px; border:1px dotted black;background-color:#CCCCCC;}
#resizer {width:200px; height:75px; background-color:#00CCFF;}
</style>

Next, dive into the script, of which the important bits are explored below (view source for full script). The script will also be quite simple, beginning with creating our Custom Event, which we'll fire when our click handler executes and changes the resizer's width.

//create a new custom event, to be fired
//when the resizer div's size is changed
var onSizeChange = new YAHOO.util.CustomEvent("onSizeChange", this);

Our click handler, to be fired when the grey container div is clicked on, looks like this; remember, it only fires the Custom Event if it seems like the click will result in a positive value for the resizer's new width — line 15 below is where we ultimately fire the Custom Event.

//when the container is clicked on, change the 
//width of the resizer -- as long as it appears
//to be a valid new size (>0).
function fnClick(e){
	var containerX = YAHOO.util.Dom.getX("container");
	var clickX = YAHOO.util.Event.getPageX(e);
	//adjust for padding in container
	var containerPadding = parseInt(YAHOO.util.Dom.getStyle("container","padding-left"), 10);
	var newWidth = clickX - containerX - containerPadding;
	
	if (newWidth > 0) {
		YAHOO.util.Dom.setStyle("resizer", "width", newWidth + "px");
		 //fire the custom event, passing
		 //the newWidth var in as an argument
		onSizeChange.fire(newWidth);
	}
}

We now have a Custom Event and are firing it at the right time, passing in the relevant data payload: the new width of the resizer div. The last step is to create a function to respond to this change and then subscribe that function to our Custom Event, onSizeChange:

//a handler to respond to the custom event that
//we're firing when the resizer changes size; we'll
//just report the new size to the subscriber div.
fnSubscriber = function(type, args) {
	var subscriber = YAHOO.util.Dom.get("subscriber");
	var newMessage = "<strong>Custom Event fired:</strong>" +
		" the new size of the resizer div is " +
		args[0] + "px.<br>";
	subscriber.innerHTML = newMessage + subscriber.innerHTML;
}

//all that remains is to subscribe our subscriber
//handler to the onResize custom event:
onSizeChange.subscribe(fnSubscriber);

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 — obviously, we only have one subscriber here, but we could have from zero to n subscribers. Moreover, Custom Events give you granular control over scope and firing order. As a result of their flexibility and power, we find ourselves using Custom Events more and more as vehicles for exposing API functionality in YUI components.

— Eric Miraglia, Yahoo Presentation Platform Engineering