Options

If there are lots of different parameters that your plugin supports, the best way of implementing it is to pass it an options object. If you haven't encountered the idea before, an options object is simply an object with properties corresponding to the parameters you would have passed.

For example, our table object has two parameters and these can be packaged into an options object as:

{n:3,m:2}

any additional parameters could be added as properties in the same way.

When you call your plugin you now have to process the options object to extract the parameters, but this is easy:

function table(options) {
 var n=options.n; 
 var m=options.m;

It is also a good idea to allow default options. After all, what if the user didn't specify one of the properties? The simplest way to do this is to use the jQuery extend(obj1,obj2) method. This adds all of the properties of the second object to the first and returns the result. Notice that the extend method is an example of a method that belongs to the jQuery constructor so you call it using $.extend and not $().extend.

So, to set defaults for n and m use:

function table(options) {
 var settings=$.extend({n:2,m:2},options); 
 var n=settings.n; 
 var m=settings.m;

With this change you can call the plugin as:

$().table();

and automatically create a 2 by 2 table or as:

$().table({m:10})

and create a 2 by 10 table.

There are some subtle points in using extend. By default it creates a shallow copy. This means if one of the properties in the first object is itself an object it is simply overwritten by any property of the same name in the second object – it isn't merged with the property of the second object.

Using options and defaults is also the recommended way to vary the operation of your plugin. That is, instead of creating two plugins that do similar jobs you should create a single plugin and use options to determine which exact job it does.

In particular you can use your plugin function as if it was a constructor for the plugins you want to use and simply pass it the name of the function you want to use.

For example, if you want to add two related plugins – plug1 and plug2 you could set up an object within your main plugin:

function plugin(method,option) {
var plugins={
 plug1: function(options){  do plug1 };
 plug2: function(options){  do plug2 };
};

To invoke the plugin you would use:

plugins[method];

and to run plug2 you would write:

$().plugin("plug2",options);

In a real implementation you would need to also check that the user has specified a valid method and remember to return something at the end of plugin.

If you know jQuery UI, you will recognize this method of invoking different sub-plugins and now you know how it works.

Of course, if the plugins you are creating are just for your own consumption, it is entirely up to you how many plugins you create as it is your own jQuery namespace that you are clogging up.

Avoiding Collisions

Up to this point our plugin has been defined in the simplest way possible so that we can concentrate on how it works. In practice, you would use a standard way of setting up the plugin to avoid the problem of clashes with the use of $. The problem is caused because other libraries use the $ as a shorthand symbol and so jQuery gives the user the option of selecting a different symbol.

So far we have used $ in all our plugin code and this will mean it will fail if the compatibility option has been used and jQuery is using some other symbol.

The correct way to set up your code is to define a local definition of $ that is safe from changes elsewhere. The standard way of doing is is to use an IIFE:

(function($){ 
 your plugin code using $
})(jQuery);

This defines the parameter $ to be the jQuery object so that your code can work in the usual way. Your plugin should also add itself to the $.fn object within this function which should be executed before anything attempts to use your plugin.

Using this form the complete table plugin is: 

(function($) {
 $.fn.table = function(options) { 
  var settings = $.extend({n: 2, m: 2}, options);
  var n = settings.n; 
  var m = settings.m;

  var table = $("<table>"); 
  var tbody = $("<tbody>"); 
  var row = $("<tr>"); 
  var cell = $("<td>"); 
  for (var i = 0; i < n; i++) { 
   var tempRow = row.clone(); 
   for (var j = 0; j < m; j++) {
    tempRow.append(cell.clone().html(i+","+j));
   } 
   table.append(tbody); 
   this.first().append(table); 
   return this; 
  } 
 })(jQuery);

The modifications needed to make it into a plugin were very few and the process was generally easy.

More to Discover

There are some advanced topics still to cover. We haven't described how to work safely with events in plugins and we haven't looked at how plugins can save data from one invocation to the next. Both are fairly easy, but are seldom necessary, so look them up when you need to.

There is also the topic of how to make your plugin available to the jQuery community, and this is just a matter of setting up the project on gitHub and creating the necessary files to let people know what is in your creation. See the jQuery website for details.

Summary

• To add a plugin to jQuery all you have to do is create a new property on jQuery.fn

• When a plugin is called this is a jQuery object of all the elements that have been selected.

• To allow chaining you have to return a jQuery object, either the original or a modified one as appropriate.

• To configure the plugin pass an options object.

• The standard way of setting up a plugin is is to use an IIFE:

  (function($){ 
  
   your plugin code using $
  
  })(jQuery);