jQuery Plugin Authoring Template

July 8th, 2010

For seasoned vets or first-time plug-in authors, here’s my basic template from which I start every jQuery plugin. It’s not all that much, but it does save some set-up time and helps to make sense of the “});” soup that tends to occur at the end of every plug-in.

Documentation

The first part, often overlooked in the excitement of writing a new shiny plugin, is the basic author info and a markup example. I find the markup example to be quite handy while developing since you can keep the markup in the file you’re currently working on, saving you the trouble of toggling back and forth between markup and JS to remember what you’re traversing or manipulating.


1:  /*
2:   *     PluginName- jQuery plugin
3:   *     written by AuthorName
4:   *     URL
5:   *
6:   *     Copyright (c) 2010 AuthorName (AuthorURL)
7:   *     Dual licensed under the MIT (MIT-LICENSE.txt)
8:   *     and GPL (GPL-LICENSE.txt) licenses.
9:   *
10:   *     Built for jQuery library
11:   *     http://jquery.com
12:   *
13:   */
14:  /*
15:   *     markup example
16:   */

Declaration and Parameters

Next comes the basic plugin function declaration, complete with the default values and user options. This is the heart of the plugin and it’s something you’ll absolutely need to include in each and every plugin, so it’s best to just keep the code lying around in working order.

1:  (function($){
2:       $.fn.PluginName = function(options) {
3:            // Default Values
4:            var defaults = {
5:                 // height: 500, width: 500
6:            };
7:            var options = $.extend(defaults, options);

Initialization

After dealing with the defaults and options, I think it makes the most sense to list all the code responsible for initializing the plugin. The two steps to this are declaring any variables being used only internally and to actually write out whatever DOM manipulations or effects need to occur right as the plugin is initialized.

1:            // Internal Variables
2:            var aVariable;
3:            // Initializing Code

Methods

Next come the guts of the plugin. We begin by binding the methods and DOM references to each instance of the markup targeted by the plugin with “return this.each(function()”. The next line helps immensely by creating a variable which is used to keep track of the markup instance. Without this variable, you’ll find that your plugins often will only work if used once per page. Next come the reused helper methods of the plugin, which I find best grouped by event bindings, general helper methods, and then finally timed events.

1:            return this.each(function() {
2:                 var obj = $(this);
3:                 // Event Bindings
4:                 $("a", obj).click(function (){
5:                      // Click Code
6:                 });
7:                 // Plugin Methods
8:                 function aMethod() {
9:                      // Method code
10:                 };
11:                 // Timed Events
12:                 // timeout = setTimeout(function, 10000);
13:            });
14:       };
15:  })(jQuery);

That’s It

And that’s it. Although pretty basic, starting a new plugin from this template rather than from scratch can save a lot of headache. I welcome you to download it, give it a try, and offer any suggestions for improvements!

Download the Basic jQuery Plugin Template.