If you’re here, I’m sure it’s no surprise jQuery is an easy library to use. jQuery may be easy, but it still has its quirks and can be difficult for some to grasp beyond basic functionality and concepts. No worries, I’ve got a simple guide here to help break down code, that may seem like overly complex syntax, into simple thoughts and patterns that can be easily understood.

Here, we’ve got a basic plugin layout:

// Shawn Khameneh
// ExtraordinaryThoughts.com
 
(function($) {
	var privateFunction = function() {
		// code here
	}
 
	var methods = {
		init: function(options) {
			return this.each(function() {
				var $this = $(this);
				var settings = $this.data('pluginName');
 
				if(typeof(settings) == 'undefined') {
 
					var defaults = {
						propertyName: 'value',
						onSomeEvent: function() {}
					}
 
					settings = $.extend({}, defaults, options);
 
					$this.data('pluginName', settings);
				} else {
					settings = $.extend({}, settings, options);
				}
 
				// run code here
 
			});
		},
		destroy: function(options) {
			return $(this).each(function() {
				var $this = $(this);
 
				$this.removeData('pluginName');
			});
		},
		val: function(options) {
			var someValue = this.eq(0).html();
 
			return someValue;
		}
	};
 
	$.fn.pluginName = function() {
		var method = arguments[0];
 
		if(methods[method]) {
			method = methods[method];
			arguments = Array.prototype.slice.call(arguments, 1);
		} else if( typeof(method) == 'object' || !method ) {
			method = methods.init;
		} else {
			$.error( 'Method ' +  method + ' does not exist on jQuery.pluginName' );
			return this;
		}
 
		return method.apply(this, arguments);
 
	}
 
})(jQuery);

You may notice the structure I’ve provided is significantly different from others. Plugins can vary depending on usage and needs. Here, it is my goal to explain the concepts in code well enough for you to understand and author a plugin in such a way that suits you best.

So, let’s break it down!

The Container: An Immediate Function

Essentially every plugin is contained in an immediate function like so:

(function(arg1, arg2) {
   // code
})(arg1, arg2);

An immediate function is, as its name insinuates, a function. What’s unique about it is it’s enclosure in parenthesis, this makes everything inside the function run within a local scope. This does not mean the DOM (global) is protected, but rather all public variables and object namespaces are inaccessible. This makes a perfect start for defining variables and objects to your hearts content without interfering with existing code.

Now since all public variables are inaccessible, that could be a problem seeing jQuery itself is, in fact, a public variable. Just like any function, immediate functions can be passed variables and objects are passed by reference. We can just pass jQuery into our immediate function like so:

(function($) {
   // run some jQuery using $ symbol locally
})(jQuery);

So what I’m doing here is passing “jQuery” as a public variable into the immediate function where I can reference it locally (inside the container) as “$”. In other words I’m calling the container as a function and passing jQuery as an argument. This also allows for compatibility with Prototype, since the public variable I am referencing is “jQuery” rather than it’s shortcode “$”. If you don’t use Prototype or any other library using “$” as a shortcode it isn’t as relevant but still good to know.

The Plugin: A Function

Every jQuery plugin is essentially a large function we shove into the jQuery namespace, while we can easily assign our function using “jQuery.pluginName = function”, but if we do so our plugin’s code isn’t protected. “jQuery.fn” is a shortcode to “jQuery.prototype”, meaning it can only be read (and not modified) when using the jQuery namespace to access it. What purpose does this actually serve you? Not much other than writing your code properly and understanding protecting your code from unwanted runtime modification. Best said, it’s just good practice!

We’ve got a basic jQuery function via a plugin:

(function($) {
 
	$.fn.pluginName = function(options) {
 
		// code here
 
		return this;
	}
 
})(jQuery);

The above code function can be run just like any other jQuery function using “$(‘#element’).pluginName()”. Notice how I include “return this;”; this small piece of code allows chainability by returning the original elements (contained in “this”) wrapped in a jQuery object. You should also note that “this” within this particular scope is a jQuery object, the equivalence of “$(‘#element’)”.

This could be summarized by stating the object returned, in the code above, by “$(‘#element’).pluginName()” is exactly the same as “$(‘#element’)”, and within your function’s immediate scope there is no need to wrap “this” into a jQuery object such as “$(this)” as it has already been done.

Multiple Elements: Understanding Sizzle

jQuery uses a selector engine called Sizzle, which supports selecting multiple elements (such as entire classes) for use with functions. This is one of the great features of jQuery, but it’s also something to be considered when developing a plugin. Even if you don’t anticipate grabbing multiple elements with your plugin, it’s still good practice to plan for such in the event.

Here I’ve added in a few pieces of code to account for and run code on multiple elements, individually:

(function($) {
 
	// Add the plugin to the jQuery (protected, "fn") namespace under "pluginName" as the function name.
	$.fn.pluginName = function(options) {
 
		// Return "this" (result of "each" is also "this") to allow for chaining the plugin
		return this.each(function() {
 
			// code here, reference each individual element by "this"
			// e.g. $(this).show();
			var $this = $(this);
 
		});
 
	}
 
})(jQuery);

In this example, I’m not using “each()” to run code over each element I have in the selector. Within the function called by “each()” the individual element being processed can be referenced in the local scope by “this” and used as a jQuery object by “$(this)”. It’s also good practice to store the jQuery object you with to manipulate rather than calling “$(this)” each time you wish to run a function. Doing such is, of course, optional and not always needed; I have included it for good measure. Also note that we will be moving the “each()” command into our individual functions, this way we can return values when calling methods.

One example of this would be a plugin that supports a “val” method for returning a value:

$('#element').pluginName('val');
// Would return a value instead of a jQuery object

Functionality: Public & Private Methods

A basic function may work for some cases, but more complex plugins will require a various supply of methods and private functions. You may be tempted to use various namespaces to provide various methods for you plugin, but it’s best not to clutter your sources with excess namespaces.

The code snippet below defines a JSON object to store public methods and demonstrates how you can use your plugin’s primary function to determine which method needs calling and call that method on each element in the selector.

(function($) {
 
	// Create a private function by creating a public variable within our plugin's container.
	var privateFunction = function() {
		// code here
	}
 
	// Create an object literal for our methods
	var methods = {
		// Define individual methods within the literal
		init: function() {
 
			// Repeat over each element in selector
			// Taken from our main function and moved into each method for flexibility
			return this.each(function() {
				// Create a jQuery object to use with this individual element
				var $this = $(this);
 
				// run code here
				// e.g. privateFunction();
			});
		},
		destroy: function() {
			// Repeat over each element in selector
			return this.each(function() {
				// run code here
			});
		}
	};
 
	$.fn.pluginName = function() {
		// Grab our method, sadly if we used function(method){}, it ruins it all
		var method = arguments[0];
 
		// Check if the passed method exists
		if(methods[method]) {
 
			// If the method exists, store it for use
			// Note: I am only doing this for repetition when using "each()", later.
			method = methods[method];
 
		// If the method is not found, check if the method is an object (JSON Object) or one was not sent.
		} else if( typeof(method) == 'object' || !method ) {
 
			// If we passed parameters as the first object or no arguments, just use the "init" methods
			method = methods.init;
		} else {
 
			// Not a method and not parameters, so return an error.  Something wasn't called correctly.
			$.error( 'Method ' +  method + ' does not exist on jQuery.pluginName' );
			return this;
		}
 
		// Call our selected method
		// Once again, note how we move the "each()" from here to the individual methods
		return method.call(this);
 
	}
 
})(jQuery);

Notice how I have placed “privateFunction” as a global. This is more than acceptable considering all is within the plugin’s container, therefore it’s only accessible to the scope of the plugin. In the plugin’s main function, I am checking if a method to be passed exists. If a method does not exist or the argument passed is an object, the “init” method is run. Lastly, if the argument passed is not an object and a method doesn’t exist, we send out an error.

Also note how each method I am using “this.each()”. When I am calling “method.call(this)” in the main function, “this” is in fact a jQuery object and is being passed into each method as “this”. So within our methods’ immediate scope it is already a jQuery object. Only in our function being called by “each()” do we need to contain “this” in a jQuery object.

Here are some usage examples:

/* Please note that these cases match the code posted earlier in this section.
Not all plugin layouts will use the same code structure. */
 
// Call method "init" on each element matching ".className"
$('.className').pluginName();
$('.className').pluginName('init');
$('.className').pluginName('init', {}); // Pass object "{}" to "init" as arguments
$('.className').pluginName({}); // Pass object "{}" to "init" as arguments
 
// Call method "destroy" on each element matching ".className"
$('.className').pluginName('destroy');
$('.className').pluginName('destroy', {}); // Pass object "{}" to "destroy" as arguments
 
// Also works
$('.className').pluginName('init', 'argument1', 'argument2'); // Pass "argument 1" and "argument 2" to "init"
 
// Incorrect
$('.className').pluginName('nonexistantMethod');
$('.className').pluginName('nonexistantMethod', {});
$('.className').pluginName('argument 1'); // Will attempt to call "argument 1" as method
$('.className').pluginName('argument 1', 'argument 2'); // Will attempt to call "argument 1" as method
$('.className').pluginName('privateFunction'); // 'privateFunction' is not a method

The above examples do show “{}”, which would represent arguments. While it will still work with the code in this section, the arguments will not be passed. Proceed to the next section for passing arguments.

Plugin Settings: Passing Arguments

Many plugins support passing parameters such as configurations and callbacks. You can pass information either by function arguments or by a JS object using key-value pairs. If your plugin supports more than one or two parameters, it’s best practice to pass parameters in an object.

(function($) {
	var methods = {
		init: function(options) {
 
			// Repeat over each element in selector
			return this.each(function() {
				var $this = $(this);
 
				// Create a default settings variable
				var defaults = {
					propertyName: 'value',
					onSomeEvent: function() {}
				}
 
				// Use extend to create settings from passed options and the defaults
				var settings = $.extend({}, defaults, options);
 
				// run code here
 
			});
		}
	};
 
	$.fn.pluginName = function() {
		var method = arguments[0];
 
		if(methods[method]) {
			method = methods[method];
 
			// Our method was sent as an argument, remove it using slice because it's not an argument for our method
			arguments = Array.prototype.slice.call(arguments, 1);
		} else if( typeof(method) == 'object' || !method ) {
			method = methods.init;
		} else {
			$.error( 'Method ' +  method + ' does not exist on jQuery.pluginName' );
			return this;
		}
 
		// Use apply to sent arguments when calling our selected method
		return method.apply(this, arguments);
 
	}
 
})(jQuery);

As seen above, an “options” argument has been added to the functions and arguments also added to the main function. If a method has been declared, that method is also removed from the arguments before passing them to the method. I have swapped “call()” for “apply()”; “apply()” essentially does the same as “call()”, with support for passing arguments. This structure also supports more than one argument, if you wish to use such instead, just modify the arguments for you methods. e.g. “init: function(arg1, arg2) {}”

If using a JS object for parameters, you may want to define a defaults variable. Once a defaults variable has been declared, you want to use “$.extend” to merge values into a final parameter object (in this case, “settings”) for use.

To demonstrate, here are a few examples of logic:

var options = {
	customParameter: 'Test 1',
	propertyName: 'Test 2'
}
 
var defaults = {
	propertyName: 'Test 3',
	onSomeEvent: 'Test 4'
}
 
var settings = $.extend({}, defaults, options);
/*
settings == {
	propertyName: 'Test 2',
	onSomeEvent: 'Test 4',
	customParameter: 'Test 1'
}
*/

Retaining Settings: Adding Persistant Data

Sometimes you’ll want to retain settings and information within your plugin, to do such the jQuery “data()” function can be used. It’s quite simple in practice, make an attempt to fetch data associated with the element and if such data doesn’t exist, create it and add it to the element. Once you add information using “data()”, make sure to keep in mind deallocating resources when no longer needed using “removeData()”.

// Shawn Khameneh
// ExtraordinaryThoughts.com
 
(function($) {
	var privateFunction = function() {
		// code here
	}
 
	var methods = {
		init: function(options) {
 
			// Repeat over each element in selector
			return this.each(function() {
				var $this = $(this);
 
				// Attempt to grab saved settings, if they don't exist we'll get "undefined".
				var settings = $this.data('pluginName');
 
				// If we could't grab settings, create them from defaults and passed options
				if(typeof(settings) == 'undefined') {
 
					var defaults = {
						propertyName: 'value',
						onSomeEvent: function() {}
					}
 
					settings = $.extend({}, defaults, options);
 
					// Save our newly created settings
					$this.data('pluginName', settings);
				} else {
					// We got settings, merge our passed options in with them (optional)
					settings = $.extend({}, settings, options);
 
					// If you wish to save options passed each time, add:
					// $this.data('pluginName', settings);
				}
 
				// run code here
 
			});
		},
		destroy: function(options) {
			// Repeat over each element in selector
			return $(this).each(function() {
				var $this = $(this);
 
				// run code here
 
				// Remove settings data when deallocating our plugin
				$this.removeData('pluginName');
			});
		},
		val: function(options) {
			// code here, use .eq(0) to grab first element in selector
			// we'll just grab the HTML of that element for our value
			var someValue = this.eq(0).html();
 
			// return one value
			return someValue;
		}
	};
 
	$.fn.pluginName = function() {
		var method = arguments[0];
 
		if(methods[method]) {
			method = methods[method];
			arguments = Array.prototype.slice.call(arguments, 1);
		} else if( typeof(method) == 'object' || !method ) {
			method = methods.init;
		} else {
			$.error( 'Method ' +  method + ' does not exist on jQuery.pluginName' );
			return this;
		}
 
		return method.apply(this, arguments);
 
	}
 
})(jQuery);

In the code above, I am checking if data for the elements exists. If data for the element doesn’t exist, settings are created by merging the the passed “options” and “defaults”, then saved using the “data()” command.

All Done: Continue Reading!

• jQuery Documentation – Plugins/Authoring
• jQuery Documentation – Context, Call, and Apply
• Alternative Method Using “$.fn.extend()”
• Another Guide Demonstrating Secondary Functions

Last but not least, I’d also highly recommend the book Javascript Patterns. Some of the best books I’ve found are code patterns, and this book can help give you a head start to developing cleaner code and plugins.

The following code overrides some functionality in ExtJS and allows windows to be resized in the same manner.

• Windows can be dragged when maximized and will resize when dragged.
• Dragging a window (cursor within 20 pixels) to top of container will maximize it.
• Dragging a window (cursor within 20 pixels) to left or right of container will resize it to that half of the container.
• The window ghost will indicate its new size according to placement when dragging.
• Windows will restore to their original size before being snapped. (Not working in ExtJS 4 version)
• Adds snapLeft() and snapRight() functions to the Ext.Window component.
• Unsnapping windows will position them relative to the original cursor position on the title bar. (v2 only)
• Supports autoloading (v2 only)