How To Develop a jQuery Plugin

jQuery is the most popular JavaScript library and many sites adopt it for dynamic effects and Ajax functionality. However, relatively few developers delve into the depths of plugin development.

In this tutorial, we will create simple plugin to explain the basics. Our code will reverse the text within one or more selected nodes — view a demonstration page.

Why Create a jQuery Plugin?

In a word: re-use. By extending jQuery, you create reusable components that can be used on any web page. Your code is encapsulated and there is less risk that you will use the same function names elsewhere.

How jQuery Works

At its core, jQuery is passed DOM elements or a string containing a CSS selector. It returns a jQuery object, which is an array-like collection of DOM nodes. One or more methods can then be chained to this set of nodes, e.g.

// color all <p> tags red
$("p").css("color", "red");

Note: although the jQuery library is named ‘jQuery’, ‘$’ is a shortcut variable that references it. Be aware that other libraries can grab ‘$’ for themselves.

How jQuery Plugins Work

jQuery allows methods to be added to its library. When called, these methods are passed the jQuery object within the JavaScript ‘this’ object. The DOM nodes can be manipulated as required and the method should return ‘this’ so other functions can be chained.

Our example plugin will be called using code such as:

// reverse the text in all <p> tags
$("p").reverseText();

We will also add two optional parameters, minlength and maxlength. When defined, the string length must fall between these limits for the reversal to occur.

The Plugin Declaration

Plugins are defined using the jQuery fn function, e.g.

jQuery.fn.reverseText = function(params) { ... };

Using ‘jQuery’ rather than ‘$’ ensures there are no conflicts with other JavaScript libraries. All our internal code should also refer to ‘jQuery’ rather than ‘$’. However, we can save a little typing and reduce the file size using an anonymous function:

(function($) {
	$.fn.reverseText = function(params) { ... };
})(jQuery);

This function runs immediately and is passed jQuery as a parameter named ‘$’. Since ‘$’ is a local variable, we can assume that it always refers to the jQuery library rather than another library that grabbed the global ‘$’ variable first.

Plugin Parameters

We require two parameters for our plugin: minlength and maxlength. It is easiest to define these as function arguments, e.g.

(function($) {
	$.fn.reverseText = function(minlength, maxlength) { ... };
})(jQuery);

// example
$("p").reverseText(0, 100);

But what if we decide to add further parameters later? Our plugin could have dozens of options — parameter handling would quickly become convoluted. As an alternative, we could pass a single JSON object, e.g.

(function($) {
	$.fn.reverseText = function(params) { ... }
})(jQuery);

// example
$("p").reverseText( { minlength: 0, maxlength: 100 } );

The first line in our reverseText function should define a set of default parameters then overwrite these with any user-defined values. The jQuery extend function can handle this for us:

// merge default and user parameters
params = $.extend( {minlength: 0, maxlength: 99999}, params);

Therefore, params.minlength is 0 and params.maxlength is 99999 unless the calling code overrides those values.

The Plugin Code

We can now write our main plugin code:

// traverse all nodes
this.each(function() {

	// express a single node as a jQuery object
	var $t = $(this);

	// find text
	var origText = $t.text(), newText = '';

	// text length within defined limits?
	if (origText.length >= params.minlength &&  origText.length <= params.maxlength) {

		// reverse text
		for (var i = origText.length-1; i >= 0; i--) newText += origText.substr(i, 1);
		$t.text(newText);

	}

});

Explanation:

1. The this.each function traverses all the jQuery DOM nodes and calls an anonymous function.
2. Within the function, ‘this’ contains a single node. A jQuery node collection is assigned to $t so we can run jQuery methods.
3. The variable origText is assigned the text string within the DOM node. newText is set to an empty string.
4. If the length of origText falls between params.minlength and params.maxlength, the loop creates a reversed text string in newText. The DOM node is then updated accordingly.

Don’t Break the Chain!

Finally, we should remember to return the jQuery object so other methods can be chained:

return this;

The Completed Code

Our plugin code is now complete:

(function($) {

	// jQuery plugin definition
	$.fn.reverseText = function(params) {

		// merge default and user parameters
		params = $.extend( {minlength: 0, maxlength: 99999}, params);

		// traverse all nodes
		this.each(function() {

			// express a single node as a jQuery object
			var $t = $(this);

			// find text
			var origText = $t.text(), newText = '';

			// text length within defined limits?
			if (origText.length >= params.minlength &&  origText.length <= params.maxlength) {

				// reverse text
				for (var i = origText.length-1; i >= 0; i--) newText += origText.substr(i, 1);
				$t.text(newText);

			}

		});

		// allow jQuery chaining
		return this;
	};

})(jQuery);

This file is saved as jquery.reversetext.js. We can then include it in any HTML page after the jQuery library has loaded, e.g.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "https://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<title>jQuery plugin: reverseText demonstration</title>
</head>
<body>

<h1>jQuery plugin: reverseText</h1>
<p>This jQuery plugin reverses all the text in the selected nodes.</p>

<ul>
<li>This text will be reversed</li>
<li>This text will not be reversed</li>
<li>reversed</li>
<li>not reversed</li>
</ul>

<script type="text/javascript" src="jquery-1.3.2.min.js"></script>
<script type="text/javascript" src="jquery.reversetext.js"></script>
<script type="text/javascript">
// reverse even-numbered LI tag text
$("ul li:even").reverseText();
</script>

</body>
</html>

The list in this page now has the text reversed on the first and third bullets (remember, the first item is numbered from 0):

Resources:

• View plugin demonstration page
• View the plugin JavaScript code
• Download the plugin and example code

You should now have a good understanding of jQuery plugin development. The SitePoint JavaScript forum is also a great resource for help and advice.

Coming soon: a new three-part tutorial describing how to build a useful page component as a jQuery plugin.