How to create a jQuery plugin

One of the fundamental principles of programming is encapsulation and reuse. These two techniques allow us to write code once and use it many times in different proyects or situations. jQuery plugins are a cool way to implement these principles on our web development project.

In the past we have review many interesting ways to use jQuery for user interface. We have seen jQuery tooltips and rollovers, rotating tabs, sliding menus, collapsible panels and more. We have also reviewed some techniques like selecting elements or removing nested elements. We will see now how to create a jQuery plugin to write all this functionality once and use it on any web project.

I have chosen the collapsible panel tutorial as a starting point to develop our plugin. We will trim down some functionality so it’s a bit more didactic, allowing us to focus on the plugin development.

Startin’

Create a new file and name it jquery.collapsible.js. This is the standard and recommended way of naming plugins.

jquery.{plugin name}.js

We will first create a wrapper so it will let us use the $ symbol within our plugin, without conflicting with other libraries, should the plugin be used in a multi library environment:

[js]

(function ($) {

//plugin code goes here

})(jQuery);

[/js]

Now, add the method constructor within the wrapper:

[js]

$.fn.collapsible = function(options) {

};

[/js]

Notice the use of the $ symbol and the fn property. All this means that we are extending jQuery with another property, collapsible, the name of our plugin, which is nothing but a function. We pass options as a parameter in case we need to provide the user with an interface to adjust things within the plugin when it is called.

On your XHTML, load the jQuery library and the jQuery plugin in that particular order.

[html]

http://jquery.js
http://jquery.collapsible.js

[/html]

Below, we will write our plugin call to create the collapsible panel:

[html]

<script type="text/javascript" >
$(document).ready(function(){
$("#panel").collapsible();
});
</script>

[/html]

That’s all we need to call our plugin.

Plugin options

We will add the following at the beggining of our collapsible function:

[js]

settings = jQuery.extend({
panel: "#panel",
hide: "#hidePanel",
show: "#showPanel",
speed: 400
}, options);

[/js]

Notice that I used jQuery instead of $. This is just to show you that you can still use jQuery within the plugin’s function. We create a new variable named settings and assign the result of calling the extend function to it, which is an static function from jQuery object. We will pass our default parameters objects to this function along with the user provided options. The extend function will merge the two of them  giving priority to the options object: whenever the user sets a value on one variable replicated on the default parameters object, it will override it.

Return

We will add the following after the options section to execute our function on the set of matched elements.

[js]

return this.each(function() {

//execute code on all matched elements

});

[/js]

And that is pretty much all the structure of our plugin. Within this function you must write the code to be executed on all elements that were matched by the selection like classes, IDs or HTML tags. This is the full code of our plugin example:

[js]

(function ($) {
$.fn.collapsible = function(options) {
settings = jQuery.extend({
panel: "#panel",
hide: "#hidePanel",
show: "#showPanel",
speed: 400
}, options);
settings.width = $(settings.panel).width();

settings.widthshow = $(settings.show).width();
$(settings.show).width(0);

return this.each(function() {
  $(settings.hide).click(function(){
    $(settings.panel).animate({marginLeft:"-"+settings.width+"px", opacity:0}, settings.speed );
    $(settings.show).show("normal").animate({width:settings.widthshow+"px", opacity:1}, settings.speed);
  });
  $(settings.show).click(function(){
    $(settings.panel).animate({marginLeft:"0px", opacity:1}, settings.speed );
    $(settings.show).animate({width:"0px", opacity:0}, settings.speed).hide("normal");
  });
});

};
})(jQuery);

[/js]

I added some more bits of code that are only relevant to this plugin. The general structure remains unchanged. Here’s the demo for the jQuery Collapsible Panel plugin (it behaves differently from last collapsible panel tutorial). You might also want to check the official jQuery documentation on plugin authoring.