jQuery is one of the most used JavaScript libraries, if not the most used one, which allows to make great things with the big set of little tools it offers to the web developers: HTML/DOM manipulation, CSS manipulation, HTML event methods, effects and animations, AJAX, utilities, …

One of the key aspects of jQuery is the possibility to extend it with new functionalities, so called plugins. For those who have a basic knowledge of jQuery and want or need to create a new jQuery plugin this post tries to be a helpful summary of good things to take into account.

Before to start

Because of the flexibility and powerful of the language, the Perl community is proud of his Tim Today motto, that is:

There’s more than one way to do it

You can consider the same for JavaScript, that’s true. The fact JavaScript is not an object oriented language but a prototype based language allows to follow the OOP paradigm in many different ways. Looking for a template code to create a jQuery plugin I found tons and not all following the same conventions and ideas.

Here I present a mix of the most accepted templates and its key aspects.

The code

Accompanying the article you can find the self documented version of the boilerplate code at my GitHub repository.

Where to start

If you are planning to create a jQuery plugin, the first places I suggest you to start reading is the Plugins/Authoring section of the project documentation. It is a great starting resource but in the real live you will find soon you need to know a bit more of that.

Using a jQuery plugin

Suppose we have a jQuery plugin called beautyLink, that transform a normal link (the <a> element) into a really nice one changing the font family, text and background color. So we need to include it in our page before start using it:

Later, to change the text color to red we could invoke a plugin’s public method like:

$('#linkID').beautyLink('color', 'red');

or to retrieve the current text color:

$('#linkID').beautyLink('color');

that is, the color method can act as a setter or getter depending if we pass a value or not.

Creating a new plugin

All right, we know how to use a plugin but we want to create a new one. The first step we need to do is to create a new JavaScript file where to place our code. As a good practice this file must contain a documentation header section with the plugin’s name, version, author contact information, license, etc

When we include the JavaScript file in a web page we need the code to be auto-executed so the plugin can be registered within the jQuery. To do so all the JavaScript code in the file must be inside the code:

This way, the code of our plugin will receive a reference to the jQuery library, the window and the document and, also, an undefined reference on the undefined parameter that we can use to compare undefined values (wow, that was too much undefineds in a sentence).

The wrapper function

To create a jQuery plugin we need to register a new function in the jQuery.fn object. This is an array where jQuery stores references to all available or included plugins in the current page. To add a new one simply write something like:

We must think which of our methods must be chainable and which ones not. For example, the getter methods must break the chainability. In our case we want a call to:

$('#linkID').beautyLink('color');

returns the red value and not a reference to the element to make another call.

Implementing chainability

When the wrapper function $.fn[pluginName] is called the this reference points to:

the selected DOM element, like when using:

$('#linkID').beautyLink('color', 'red');

or

a list of selected DOM elements, like when using:

$('a').beautyLink('color', 'red');

Next code shows a very basic wrapper function that initializes a Plugin instance for each selected element. This results in a chainable call that returns a reference to the same element ready to make another chained call:

Avoiding chainability

The solution to avoid a method were chainable is easy, simply doesn’t write the this.each() and execute code on the first occurrence, that is, the this[0].

This will be more clear in the final code.

The jQuery.data() function

We make use of the $.data() function in our code so a short explanation is required. The $.data() function allows to store arbitrary data on an element (or get is value).

It is important because we store a reference to the Plugin instance on each element it is applied. This allow us to check if an element has already applied a plugin or we need to instantiate it. This will be clarified in the final wrapper function code.

The backbone wrapper function code

With all the above in mind, we can write our final plugin’s wrapper function. To summarize:

If plugin is called without arguments, then the plugin is initialized and a reference is stored in the DOM element.

If a plugin’s method is called and it isn’t a getter method, then the method is called maintaining chainability.

If a plugin’s method is called and it is a getter method, then we return a value and break the chainability.

Take into account, we have also defined an array where to specify which method can act as getters when they are invoked without any argument:

$.fn[pluginName].getters = ['someGetterMethod'];

To be continue…

We have seen the basis on how to create a jQuery plugin and learnt about the importance of the wrapper function, which is the entry point to our plugin. In the next post I will explain how we can organize our plugin code, the responsible to implement functionality, how to create private and public method, etc.