You’re trying to build something with jQuery that requires functionality that doesn’t exist in the jQuery core. The problem is one that other developers have likely run into before, and you think a plugin may exist. Where should you start looking to find plugins, and how should you evaluate the plugins that you find?

Search through the following repositories for jQuery plugins:

There are a few places around the Web that jQuery plugins may be found. Because of the nature of jQuery plugins, there are certain open source hosting sites that tend to attract jQuery plugins more than others. Additionally, the jQuery project hosts a central repository for jQuery plugins at http://plugins.jquery.com.

It’s best to look through all of the available resources and collect several potential plugins, if they are available, for your review. Plugins that are built to solve the same problem often take very different approaches or were built for alternate versions of the jQuery core library.

When looking for a jQuery plugin, the following are the best steps to find the most updated and recent versions of plugins.

{searchterm} "jquery*.js" - Best practice plugin naming is jquery-{myplugin}.js or 
jquery.{myplugin}.js

 {searchterm} "*jquery.js" - Alternate best practice plugin naming

After searching for an existing jQuery plugin to fit your needs, the plugins that were found either don’t meet your needs or are not constructed in a way that you can take advantage of them properly. Is it worth writing a new jQuery plugin that can be shared with others who have the same need?

There’s no cut and dried solution to this problem. The number of available jQuery plugins is large, but there are valid cases where plugins don’t exist to meet a particular need.

In my opinion, the decision to write and publish your own jQuery plugin comes down to three things:

You’ve decided that you want to write a jQuery plugin. How do you write a plugin in jQuery? What best practices should you follow?

jQuery is designed to make writing a plugin very simple and straightforward. You can extend the existing jQuery object by writing either methods or functions. Simply declaring the following JavaScript after inclusion of the jQuery core library will allow your code to use your new custom method or function.

jQuery.fn.goShop = function() {
  return this.each(function() {
    jQuery('body').append('<div>Purchase: ' + this.innerHTML + '</div>'),
  });
};

jQuery('p').goShop();

jQuery.checkout = function() {
  jQuery('body').append('<h1>Checkout Successful</h1>'),
};

jQuery.checkout();

Attaching new methods and functions to the main jQuery object are a powerful feature of jQuery. Many of the core methods are built into the library using this same technique. By leveraging this existing foundation in jQuery, users of jQuery and users of your plugin have a fast and concise way to add new functionality, extend existing functionality, and mold the jQuery code into whatever form suits them best. This flexibility is a key feature and enables jQuery and its plugins to be used by a wider audience.

The choice to extend jQuery via a new method or a function mainly depends on the needs of the developer. In general, focusing on extending jQuery via adding a new method is best because this allows that new method to be chained along with other methods, and it allows the code in the method to take advantage of jQuery’s selector engine.

Your first plugin adds a method to jQuery. However, there are a few options that would be helpful to others if they were exposed properly. What is the best method of passing options into a custom method?

Options are best passed into your custom plugin method via an options object. Using a single options object to pass in parameters promotes cleaner code, is easier to work with, and provides flexibility down the road.

When allowing options to be utilized in your plugin, it’s wise to provide sensible defaults. After providing sensible default options, it’s also important that your plugin provide a method for the user of the plugin to override the defaults. Both of these goals are easily accomplished by declaring a default options object, overriding the default options with user-supplied options and the jQuery extend() method, and then utilizing the options in your code:

jQuery.fn.pulse = function(options) {
  // Merge passed options with defaults
  var opts = jQuery.extend({}, jQuery.fn.pulse.defaults, options);

  return this.each(function() {
    // Pulse!
    for(var i = 0;i<opts.pulses;i++) {
      jQuery(this).fadeTo(opts.speed,opts.fadeLow).fadeTo(opts.speed,opts.fadeHigh);
    }

    // Reset to normal
    jQuery(this).fadeTo(opts.speed,1);
  });
};

// Pulse plugin default options
jQuery.fn.pulse.defaults = {
  speed: "slow",
  pulses: 2,
  fadeLow: 0.2,
  fadeHigh: 1
};

By specifying option defaults, developers using your plugin have the ability to provide as many or as few options when they call your function. It is important to place your options’ defaults after you’ve defined your plugin entry method; otherwise, you will encounter an error:

// Override only one option
jQuery('p').pulse({pulses: 6});

// Override all options
jQuery('p').pulse({speed: "fast", pulses: 10, fadeLow: 0.3, fadeHigh: 0.8});

Lastly, by specifying your options as an object attached as a child to your plugin function, the default options may be overridden only once in a project. A developer then has the ability to specify their own set of default options, minimizing the amount of code required to produce the desired behavior:

// Plugin code included above

// Reset pulse default options
jQuery.fn.pulse.defaults = {
  speed: "fast",
  pulses: 4,
  fadeLow: 0.2,
  fadeHigh: 1
};

// This call will use the new defaults
jQuery('p').pulse();

Supporting options in your plugin is a powerful way to add tremendous flexibility to the plugin. Plugins that support a rich set of options are more likely to fit the needs of a wider audience, perform a wider variety of tasks, and generally gain more popularity than plugins that don’t support options.

Including a set of default options with your plugin is another way to give developers who use your plugin flexibility and choice in how the plugin is implemented. A handy side benefit is that the plugin can always rely on certain options being defined, reducing the amount of code required to check whether an option has been passed. This leaves plugin users with the ability to override a single option, multiple options, or even all of the options every time they call your plugin. Lastly, by attaching the default options to the jQuery object, the options can be overridden globally, giving your users another tool to leverage in new and creative ways.

Other JavaScript libraries make use of the $ shortcut. jQuery itself uses $ only as a shortcut, with the main object being named jQuery. How can you ensure that your plugin maintains compatibility with other plugins and libraries?

jQuery itself uses the $ function as a custom alias for the jQuery object. When jQuery is set into compatibility mode, it passes back control of the $ alias to the original library that defined it. Plugins can be crafted to use the same technique.

By wrapping your plugin in an anonymous function and immediately executing that function, the $ shortcut is kept inside the plugin. Code outside of the plugin can use $ normally. Inside the plugin, $ will reference the jQuery object as normal:

;(function($) {
  $.fn.pulse = function(options) {
    // Merge passed options with defaults
    var opts = $.extend({}, $.fn.pulse.defaults, options);

    return this.each(function() {
      // Pulse!
      for(var i = 0;i<opts.pulses;i++) {
        $(this).fadeTo(opts.speed,opts.fadeLow).fadeTo(opts.speed,opts.fadeHigh);
      }

      // Reset to normal
      $(this).fadeTo(opts.speed,1);
    });
  };

  // Pulse plugin default options
  $.fn.pulse.defaults = {
    speed: "slow",
    pulses: 2,
    fadeLow: 0.2,
    fadeHigh: 1
  };
})(jQuery);

Wrapping your distributed code in an anonymous function is a very straightforward and simple step that adds several features and ensures that your plugin code can play nicer in the wider world that your users may live within.

Adding a semicolon at the beginning of your function definition helps protect against another developer who may have forgotten to include an ending semicolon in their library. The JavaScript language breaks statements on newline by default, but many users take advantage of minimization tools that compress the entire set of JavaScript in their projects into a single file. This process removes the line endings and can cause errors if your code follows immediately after. Adding the initial semicolon is a quick and easy trick to protect against that possibility.

The open parenthesis immediately begins the anonymous function definition. Within our anonymous function, we define a function that passes the variable that we want to use in place of the fully named jQuery object. In this case, we want to take advantage of using $ as the variable. Defining an additional function is required because of the way the JavaScript language handles scoping. In more traditional languages such as Java and C++, scope is limited to the block statement. In JavaScript, scope is wrapped in functions. Therefore, the reason for using a function here is really to set up a scope boundary that we can define our plugin within.

What follows is a new version of our plugin, with the sole change of swapping out the way we utilize the jQuery object. Because we’ve wrapped this plugin anonymously and limited the scope of the $ variable, we can now use $ freely without conflict from any other code.

The last line wraps up the scoping function and anonymous function with a close bracket and close parenthesis, respectively. The last bit is what actually calls our anonymous function immediately after it has been defined. This is where we tell our function to pass in the jQuery object, which is what gets renamed to $ within our function. Lastly, we close off our new statement with a semicolon to protect against JavaScript minimization and compression errors.

The $ shortcut can be incredibly useful in writing JavaScript code. It cuts down on code size, promotes good code design, and has become extremely popular and well known. Thus, many libraries take advantage of the $ shortcut, tying it into their own context. With each library supporting their own version of the $ shortcut, conflicts can easily arise. By wrapping your plugin code within an anonymous function, you can ensure that your plugin maintains a level of scope around usage of the $ shortcut that will reduce the potential for conflicts with other JavaScript libraries.

One additional side effect of wrapping your plugin in an anonymous function, as described earlier, is that a closure is created. Utilizing a closure in JavaScript aids in properly namespacing any methods or variables that you may need to define, further reducing the chance for variable names or function names to conflict with other code.

Your plugin code is growing and needs to be organized. How can you implement a private method that’s unavailable to code outside your plugin?

By utilizing the plugin design pattern started in Recipe 12.4, private functions may be defined normally within the anonymous function that we’ve wrapped our plugin in. Because the function is enclosed in an anonymous function, outside code won’t see our private method. Code outside will only be able to see functions or methods that are attached to the jQuery object.

;(function($) {

  $.fn.pulse = function(options) {

    // Merge passed options with defaults
    var opts = $.extend({}, $.fn.pulse.defaults, options);

    return this.each(function() {
      doPulse($(this),opts);
    });
  };

  function doPulse($obj,opts) {
    for(var i = 0;i<opts.pulses;i++) {
      $obj.fadeTo(opts.speed,opts.fadeLow).fadeTo(opts.speed,opts.fadeHigh);
    }

    // Reset to normal
    $obj.fadeTo(opts.speed,1);
  }

  // Pulse plugin default options
  $.fn.pulse.defaults = {
    speed: "slow",
    pulses: 2,
    fadeLow: 0.2,
    fadeHigh: 1
  };

})(jQuery);

Because we now have our plugin wrapped in an anonymous function, defining private functions within our plugin is as simple as adding a new function as you normally would.

Grouping and organizing your plugin with public and private methods offers many advantages to your users and to the plugin author. As your plugin matures and you receive feedback from the community, you can leverage the use of public and private methods to provide a consistent API between plugin versions. The consistency of your API can be a major factor in your plugin’s success.

The ability to break code down into private and public messages also has significant advantages in code organization as your plugin grows. Well-organized code is easier to read, to maintain, and to test. Well-tested, clean code can lead to less error-prone code.

Several plugins utilize the metadata plugin to pass custom options into their methods. How can integration with the metadata plugin be constructed?

Leveraging the metadata plugin is as simple as checking whether the plugin is available and then extending your plugin options with the metadata parameters. Using this technique, you can supply default options when making the call to your plugin and override those default options for each object to be operated on through the metadata written into the markup:

<!-- Include the metadata plugin -->
<script type="text/javascript" src="metadata/jquery.metadata.js"></script>

<!-- Example of markup containing metadata -->
<p class="{pulses: 8, speed: 'slow'}">Starship Enterprise</p>
<p>Battlestar Galactica</p>
<p class="{speed: 100}">Serenity</p>

;(function($) {
  $.fn.pulse = function(options) {
    // Merge passed options with defaults
    var opts = $.extend({}, $.fn.pulse.defaults, options);

    return this.each(function() {

      // Merge in the metadata elements for this specific node
      var o = $.metadata ? $.extend({}, opts, $.metadata.get(this)) : opts;

      doPulse($(this),o);
    });
  };

  function doPulse($obj,opts) {
    for(var i = 0;i<opts.pulses;i++) {
      $obj.fadeTo(opts.speed,opts.fadeLow).fadeTo(opts.speed,opts.fadeHigh);
    }

    // Reset to normal
    $obj.fadeTo(opts.speed,1);
  }

  // Pulse plugin default options
  $.fn.pulse.defaults = {
    speed: "slow",
    pulses: 2,
    fadeLow: 0.2,
    fadeHigh: 1
  };
})(jQuery);

Including the metadata plugin is a great example of how jQuery plugins can build off of one another. The jQuery plugin ecosystem is vast, and chances are there are other plugins that you can utilize.

To include and use the metadata plugin, you first must actually include it into your script. The metadata plugin is hosted along with jQuery at Google Code. The metadata plugin works by allowing you to embed additional data into your HTML, while still producing valid HTML. We take advantage of this by allowing users to embed element-specific options into the class element of the items we can operate on.

The options are embedded into the HTML using standard JSON. All of the options may be embedded, or none may be embedded; it’s up to your users. There are several other methods and options for using the metadata plugin that are described on its documentation page.

Within our plugin, we first check to see whether a user has included the metadata plugin. This is done to ensure that we keep this additional feature optional and to provide backward compatibility, if necessary. Because the metadata plugin operates on a single element, we split up how we handle options. The first step is to use the options provided when the plugin was called. These options are extended with our default options, creating our starting point for this first instantiation of our plugin. The second step is to extend those locally default options with the metadata that may be defined for each element. All that is required is for us to extend our locally default options with the metadata options, if the metadata plugin exists.

The metadata plugin provides another option for users of your plugin to pass in options. Providing options to potential users is a great way to show that you are committed to your plugin, being a good citizen of the jQuery ecosystem. The metadata plugin is also a great way to offer your users the ability to write less code by embedding custom options into the HTML elements.

In addition to making your plugin available through the jQuery function, you want to expose a static function. How can you add a static function to your jQuery plugin?

Adding a static method to your plugin requires extending the jQuery object in much the same way you would add a method. The difference is simply that functions are called without using jQuery selectors:

;(function($) {
  $.fn.pulse = function(options) {
    // Merge passed options with defaults
    var opts = $.extend({}, $.fn.pulse.defaults, options);

    return this.each(function() {

      // Merge in the metadata elements for this specific node
      var o = $.metadata ? $.extend({}, opts, $.metadata.get(this)) : opts;

      doPulse($(this),o);
    });
  };

  function doPulse($obj,opts) {
    for(var i = 0;i<opts.pulses;i++) {
      $obj.fadeTo(opts.speed,opts.fadeLow).fadeTo(opts.speed,opts.fadeHigh);
    }

    // Reset to normal
    $obj.fadeTo(opts.speed,1);
  }

  // Define our base to add to
  $.pulse = {};

  // Static Function
  $.pulse.impulse = function($obj) {
    var opts = {
      speed: 2500,
      pulses: 10,
      fadeLow: 0.2,
      fadeHigh: 0.8
    };
    doPulse($obj,opts);
  }

  // Static Function
  $.pulse.warpspeed = function($obj) {
    var opts = {
      speed: 25,
      pulses: 100,
      fadeLow: 0.2,
      fadeHigh: 0.8
    };
    doPulse($obj,opts);
  }

  // Pulse plugin default options
  $.fn.pulse.defaults = {
    speed: "slow",
    pulses: 2,
    fadeLow: 0.2,
    fadeHigh: 1
  };
})(jQuery);

Calling the static methods available in your plugin is very straightforward, requiring only that you explicitly pass a valid object to operate on:

// Call the impulse method on the first element returned
jQuery.pulse.impulse(jQuery('p:first'));

// Call the warpspeed method on the first element returned
jQuery.pulse.impulse(jQuery('p:first'));

Adding a static function within the scope of your plugin only requires adding a way for code outside of your plugin to call it. This is accomplished by attaching the functions to the jQuery object.

In the previous example, we’ve added a namespace object to aid in organizing our code better. If all that your plugin required was a single static function, it would be completely appropriate to expose your static function without adding a namespacing object. After adding our namespace object, we simply define our functions like normal and attach them to the namespace object we created. Doing this exposes our function to the global namespace, while allowing the contents of the functions to access private functions and variables.

Taking advantage of the static function is as simple as calling it using the jQuery object we attached it to. This function is called without utilizing jQuery selectors, so in order to operate on a DOM element, that element must be explicitly passed to the function.

A static function attached to the jQuery object is another example of the flexibility of the jQuery library. Your entire plugin could be made up of adding static functions that simply extend the jQuery core in interesting new ways. A static function could be the entry point you provide to your plugin, or it could be a simple shortcut method you’ve found useful that’s packaged in your plugin in a way that makes it easier to share with other developers. Whatever the need, static functions can be a useful and powerful tool when building your own jQuery plugin.

You want to raise the quality and reliability of your jQuery plugin by creating unit tests for it. How do you write and ship tests with your jQuery plugin?

The easiest method to write unit tests for a jQuery plugin is to utilize QUnit, the same unit testing framework that the jQuery project uses. With QUnit, you can write your tests right in JavaScript and ship them with your plugin for your users to run in their own browsers:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <script type="text/javascript" src="../jquery-1.3.2.min.js"></script>
  <script type="text/javascript" src="metadata/jquery.metadata.js"></script>
  <script type="text/javascript" src="jquery.pulse.js"></script>

  <link rel="stylesheet" 
href="http://jqueryjs.googlecode.com/svn/trunk/qunit/testsuite.css" type="text/css" 
media="screen" />
  <script type="text/javascript" 
src="http://jqueryjs.googlecode.com/svn/trunk/qunit/testrunner.js"></script>
</head>
<body>

  <script type="text/javascript">
    module("Testing the jQuery Pulse Plugin");
    test("Test Pulse with basic options", function() {
      $("div.starship").pulse();

      equals($("#enterprise").css("opacity"),1,"The element should be visible");
      equals($("#galactica").css("opacity"),1,"The element should be visible");
    });

    test("Test Impulse", function() {
      $.pulse.impulse($("#galactica"));

      equals($("#galactica").css("opacity"),1,"The element should be visible");
    });

    test("Test Warp Speed", function() {
      $.pulse.warpspeed($("#enterprise"));

      equals($("#enterprise").css("opacity"),1,"The element should be visible");
    });
  </script>

  <div id="main">
    <div class="starship" id="enterprise">USS Enterprise - NC-1701-A</div>
    <div class="starship" id="galactica">Battlestar Galactica</div>
  </div>

</body>
</html>

Learning how to effectively test code is beyond the scope of this chapter. The tests written in the previous example are intended to simply show an example of what can be done with unit testing. Chapter 18 goes into great detail about unit testing and specifically the QUnit framework. For a discussion on how to use QUnit, what types of things you can test, and how to effectively test your code, please refer to that chapter.

Shipping unit tests with your plugin is another great way to show developers you are committed to the success and stability of the code that you publish. This builds trust with your user base and shows that your plugin is a good member of the jQuery plugin ecosystem. Tests also make it easy for users of your plugins to find bugs that can creep up in another runtime environment, such as a different browser. This allows you, the plugin author, to better address the bug that was found by having a working test bed, allowing you, the plugin developer, to directly address the bug that was found.