This post aims to be a tutorial for helping you with writing your own jQuery plugins. As you will see, writing a plugin is not difficult to understand, provided that the tutorial in question is able to guide you in a step-by-step tour through the development process of a jQuery plugin. In this post I'll follow a step-by-step approach, hoping that this will be useful. If you're ready, we can start.
Step 1: creating the plugin namespace
Every jQuery's plugin starts with creating a namespace where the plugin will live:
(function($) {
//...
})(jQuery);
The namespace is actually the jQuery's main object itself, so the plugin is actually telling to jQuery that it has to be considered as a part of the library or, more precisely, as one of its extensions. In fact, a plugin is nothing more than an extension of jQuery.
Step 2: defining the plugin name
Now we need to define the name of our plugin. Just for this example, we'll call it myPlugin:
(function($) {
$.fn.myPlugin = function() {
//...
};
})(jQuery);
As you can see, our plugin is nothing more than a function attached to the fn object of jQuery. Attaching our plugin to this object is fundamental: by doing so, our plugin will be available in the jQuery's chain, for example $('#test').myPlugin(), and it will be accessible on every component or object in that chain.
Step 3: defining the plugin options
Plugin options are just an object literal passed to our plugin function and set up using the $.extend() method:
(function($) {
$.fn.myPlugin = function(options) {
options = $.extend({
// default options
}, options);
};
})(jQuery);
The first object literal passed to $.extend() contains the default options that will be used if the plugin is invoked without options. For example:
options = $.extend({
text: 'Hello World'
}, options);
So if we call our plugin like so:
$('#test').myPlugin(); // uses 'Hello World'
then the default value for the text option will be used, because we didn't specify an option. On the contrary, if we specify that option:
$('#test').myPlugin({
text: 'Goodbye' // uses 'Goodbye'
});
then the value specified when we invoke our plugin will be used instead of the default value. Inside our plugin, we can reference an option by using a normal object notation, for example options.text.
Step 4: defining the plugin body
The plugin body must return the jQuery's object where it's used. Further, since our plugin could be used on a set of elements, it also must be available on multiple elements:
(function($) {
$.fn.myPlugin = function(options) {
options = $.extend({
// default options
}, options);
return this.each(function() {
// plugin body
});
};
})(jQuery);
As you can see, we've used the return statement combined with the jQuery's each() method. The keyword this refers to the current object or element where the plugin is used. Inside this function, we can access the current element by using $(this):
(function($) {
$.fn.myPlugin = function(options) {
options = $.extend({
text: 'Hello, World!'
}, options);
return this.each(function() {
$(this).text(options.text);
});
};
})(jQuery);
For example, if we have an HTML element like this:
<div id="test">Foo</div>
We can use our plugin as follows:
$('#test').myPlugin({
text: 'Bar'
});
Now the text of the element is 'Bar'. Instead, if we use our plugin without options:
$('#test').myPlugin();
Now the text of the element is 'Hello, World!', because the default option of our plugin has been used.