The Basics of Writing a jQuery Plugin

jQuery is a great javascript framework that has been growing steadily in popularity. One of its best features is its extensibility. jQuery has a lightweight core that can easily be extended to provide additional functionality through plugins. Using a jQuery plugin looks something like this:

$("selector").pluginname();

While writing one-off scripts and applications is necessary, often there are components of a project that can be reused in the future. A good idea is to encapsulate these components in a plugin. The jQuery documentation has a Plugin Authoring Guidelines page which has some great information, but I have found it to be an impractical guide.

After doing some reading and developing a couple of plugins on my own, I have found the following template ideal for developing jQuery plugins:

(function($) {
  $.fn.pluginname = function(options) {
    options = $.extend({
      optionOne: 'defaultValue',
      optionTwo: { partOne: 'defaultValue' }
    }, options);

  $(this).each(function() {
    /* Plugin Code Here */
    });
  }
})(jQuery);

Now let me break down each part of the template and explain why each is necessary.

The Wrapper is a Closure

(function ($) { /* plugin code */ })(jQuery);

Using '$' is desirable when using jQuery because it is terse, requiring fewer keystrokes and is an assumed default in the jQuery community. However, many other frameworks and scripts use the symbol, so for compatibility reasons, it cannot be assumed that it is available. When developing a plugin, this consideration is especially important because the environment that the plugin will be deployed to is unknown.

By wrapping our plugin in a closure we are able to use the '$' symbol throughout our plugin without worrying about namespace issues. Additionally, any helper functions or objects that we need for our plugin will not be exposed to the global namespace and instead will live inside our plugin only.

Assigning the Plugin Name

$.fn.pluginname = function(options) { }

This assignment allows us to use our plugin as a jQuery function as shown at the very beginning of this post. Rather than letting your plugin be a nest of functions and objects that would clutter the namespace if they were simply copied and pasted into your script or included as a script separately, your plugin will exist only as a function call on jQuery objects. When working on larger projects this is important.

Using Default Values with an Options Argument

options = $.extend({ }, options);

When developing a jQuery plugin, it is best to avoid having many arguments in favor of using a single options argument. This makes it much easier to make settings optional as well as have some defaults set. By having a single options argument you can use the jQuery.extend utility to assign defaults without overwriting values that a user has passed in.

It is also good practice to make as much of your plugin configurable by options as possible. This will allow your users to have a large amount of control without having to mess around with the internals of the plugin. As an example, authors of plugins that perform an animation will often have a string arguement that controls the type of animation that is done. They expect values such as 'fade' or 'slide'. The accepted way to handle animations is to instead use the animate method which will give the user more complete control.

Conclusion

Hopefully this template is helpful in developing jQuery plugins. If you have seen or put together a cool plugin be sure to drop it in the comments. Also be sure to let me know of any other good tips you have for setting up a plugin for jQuery.