Intereactive Web Design - Sugar Land, TX

Custom events in Mootools classes allow you to run a set of code when an event occurs in the Class. An example would be “onSuccess” when running an ajax (Request) call, which allows you to run some javascript when the class says that the ajax request is a “success”. If you have ever been witting a class in Mootools and wondered how the custom events work or are used, then you are definitely not alone.

This tutorial assumes you have basic Mootools knowledge and a simple understanding of how classes in Mootools work. If you aren’t there yet, here is a great tutorial on Mootools classes: The Mootorial

The Code

Lets jump right in and say that we are writing a simple class that will show/hide a div on our page. In addition we want to know when that div has been shown or hidden so we will write a custom event for “onShow” and “onHide”. We’ll walk through each step to make thing crystal clear because even as I was digging through the docs and other examples, I found that I had a flawed understanding of how these work.

Our test class

var PopUp = new Class({
	Implements: [Events, Options],

	options: {
		/*
		onShow: $empty,
		onHide: $empty,
		*/
		element_id: null
	},
	initialize: function(options) {
		this.setOptions(options);
	},
	show: function() {
		$(this.options.element_id).setStyle('display', 'block');
		this.fireEvent('show');
	},
	hide: function() {
		$(this.options.element_id).setStyle('display', 'none');
		this.fireEvent('hide');
	}
});

Here we initialize the Class (usually in ‘domready’)

popup = new PopUp({
	element_id :	'popup_div',
	onShow:function(){
		alert('The "show" event was fired');
	},
	onHide:function(){
		alert('The "hide" event was fired');
	}
});

Explanation – Part 1

The following code tells the class what we want to implement. You need both the Events and the Options for custom events to work

	Implements: [Events, Options]

Explanation – Part 2

The following code is where we set the options for the class. You will notice that both onShow and onHide are commented out. Mootools doesn’t need these values implicitly declared because when you pass them in (when you initialize the class), Mootools automatically sets them as events. Mootools will take any option passed in that has a function associated with it and will convert that to an event. They are listed here in the options list for reference only.

	options: {
		/*
		onShow: $empty,
		onHide: $empty,
		*/
		element_id: null
	}

Explanation – Part 3

The following code is needed because when the class is initialized the onShow and onHide as passed in as Options. This threw me for a huge loop when I was trying to use custom events because I thought I was trying to set up an “event” and not an “option”. I didn’t know that Motools converted the option into an event.

	initialize: function(options) {
		this.setOptions(options);
	}

Explanation – Part 4

This is where the custom event is actually fired. When the class has done something we want to hook to (onShow in this case), we call “this.fireEvent(’show’);“. You will notice that it uses “show” instead of “onShow”. Mootools will automatically convert the two. This is done to keep things semantic. The event you are firing is “show” and in you class initialization you want to run a function on the Event (or onShow). Also note that running “this.fireEvent(’onShow’);” will work but is not recommended.

	show: function() {
		$(this.options.element_id).setStyle('display', 'block');
		this.fireEvent('show');
	}

A Working Example

I’ve put all the pieces of this post together in a working example so you can see how things work in real time. Custom Event Example