Plug me: Writing your own plugins

Writing your own plugins for jQuery is quite easy. If you stick to the following rules, it is easy for others to integrate your plugin, too.

Plugin Naming

Find a name for your plugin, lets call our example "foobar". Create a file named jquery.[yourpluginname].js, eg. jquery.foobar.js

Adding a Custom Method

Create one or more plugin methods by extending the jQuery object, eg.:

 jQuery.fn.foobar = function() {

   // do something

 };

Which will then be accessible by performing:

 $(...).foobar();

Default Settings:

Create default settings that can be changed by the user, eg.:

 jQuery.fn.foobar = function(options) {

   var settings = jQuery.extend({

     value: 5, name: "pete", bar: 655

   }, options);

 };

You can then call the plugin without options, using the defaults:

 $("...").foobar();

Or with some options:

 $("...").foobar({ value: 123, bar: 9 });

Documentation

If you release your plugin, you should provide some examples and documentation, too. There are lots of plugins available as a great reference.

Now you should have the basic idea of plugin writing. Lets use this knowledge and write one of our own.

Checkbox Plugin

Something lots of people, trying to manipulate forms with jQuery, ask for, is checking and unchecking of radio buttons or checkboxes. They end up with code like this:

 $(":checkbox").each(function() {

   this.checked = true;

   this.checked = false; // or, to uncheck

   this.checked = !this.checked; // or, to toggle

 });

Whenever you have an each in your code, you might want to rewrite that as a plugin, pretty straightforward:

 jQuery.fn.check = function() {

   return this.each(function() {

     this.checked = true;

   });

 };

This plugin can now be used:

 $(":checkbox").check();

Now you could write plugins for both uncheck() and toggleCheck(), too. But instead we extend our plugin to accept some options.

 jQuery.fn.check = function(mode) {

   // if mode is undefined, use 'on' as default

   var mode = mode || 'on';

   

   return this.each(function() {

     switch(mode) {

       case 'on':

         this.checked = true;

         break;

       case 'off':

         this.checked = false;

         break;

       case 'toggle':

         this.checked = !this.checked;

         break;

     }

   });

 };

By providing a default for the option, the user can omit the option or pass one of "on", "off", and "toggle", eg.:

 $(":checkbox").check();

 $(":checkbox").check('on');

 $(":checkbox").check('off');

 $(":checkbox").check('toggle');

Optional Settings

With more than one optional setting, this approach gets complicated, because the user must pass null values if he wants to omit the first parameter and only use the second.

The use of the tablesorter in the last chapter demonstrates the use of an object literal to solve this problem. The user can omit all parameters or pass an object with a key/value pair for every setting he wants to override.

For an exercise, you could try to rewrite the Voting code from the fourth section as a plugin. The plugin skeleton should look like this:

 jQuery.fn.rateMe = function(options) {

   // instead of selecting a static container with 

   // $("#rating"), we now use the jQuery context

   var container = this;

   

   var settings = jQuery.extend({

     url: "rate.php"

     // put more defaults here

   }, options);

   

   // ... rest of the code ...

   

   // if possible, return "this" to not break the chain

   return this;

 });

And allowing you to run the plugin like so:

 $(...).rateMe({ url: "test.php" });