Creating your first jQuery plugin

January 26, 2009

jQuery is pretty cool, isn’t it. The developers were actually remarkably clever when designing it allowing for it’s renowned ‘chanability’. Even though you may not know what it means, or even have heard of it, you’ve probably used it. And that’s one of the bestest things about software design, getting people to use quite clever programming methods without even knowing that you’re using them. But I think that it’s important to know, at least at a basic level, what’s going on behind the scenes.

A bit of background

So onto the clever and scary bit – what’s under jQuery’s hood? Well, jQuery, or the $, is an object. And each of the functions which you use it for returns an object of type jQuery. Now, objects (or properly object orientism) is a large and complicated topic, so I won’t go into it here, but you can get a heads up on it on wikipedia’s article on Object Oriented Programming. I’d recommend learning about it if you don’t know it already, it’s extremely powerful and I use it all the time in PHP. So jQuery functions returning a jQuery object means that you can just keep on adding more and more functions to the chain. Let me demonstrate with an example:

$("selector").css("some", "property").animate("arguments").click (function () {} ) /*and so on */

The beginnings of your plugin

I’m going to say it now. The plugin that I’m going to show you for this tutorial won’t be very much use for anything really. But it will show you the principles so that you can go off and build your own. I’m going to show you how to create a simple plugin which conforms to the design pattern of jQuery, i.e. the plugin will made in such a way that you can continue to chain functions after it. This example plugin will be called lookAtMe, and will make the elements specified fade in and out, making the user look at them (in theory!)

To start with, let’s forget that the plugin has to be chainable, and just write a function to fade things in and out. This can be easily done with the fadeIn() and fadeOut() functions. One of the best things about extending jQuery is that it is almost too easy. If you put your function inside a couple of lines of code, you can use this.each, and it’ll automatically iterate through the chosen DOM elements allowing you to use the this keyword as you would in a jquery .each() call. And to tell jQuery that you’re adding a plugin, all you need to do tell jQuery it’s name, put an equals sign, then write your function as normal. Easy!

jQuery.fn.lookAtMe = function ()
{
	this.each(function()
	{
		$(this).fadeOut().fadeIn();
	});
};

Too easy, right? Right! There is just a single word missing from the plugin. If you do a test with chaining on your plugin, you’ll find it doesn’t work (hint: try $("p").lookAtMe().css("background-color", "red") – you’ll find that you get some kind of javascript error). To fix it, all you need to do is to return the result of the function (which cleverly already returns a jQuery object!) from your function, and as if by magic, everything works! The final code is listed below. Although there is one important change, which is that I have changed the $ to jQuery.

jQuery.fn.lookAtMe = function ()
{
	return this.each(function()
	{
		jQuery(this).fadeOut().fadeIn();
	});
};

Why use `jQuery` instead of `$` in the plugin?

There are a lot of javascript libraries out there, and they all like to use the magic $ function. Well, it’s no more magic than any other function except that it’s convenient and easy to pick out, so a great choice for a function name. jQuery, Mootools, prototype and many others just happen use this as their main function name, so it’s best to use jQuery instead of $ just incase the person using your plugin uses one of the other libraries. There’s a line in jQueries code by the way which the equivalent of: jQuery = $ (but is a bit more complicated and boring).

Use it

Now you can use your plugin the same as any of the other jQuery functions which you use all the time.

This is an important message

Nice.