Essential jQuery Plugin Patterns

Filed under Javascript

I occasionally write about implementing design patterns (http://addyosmani.com/resources/essentialjsdesignpatterns/book/) in JavaScript. They’re an excellent way of building upon proven approaches to solving common development problems, and I think there’s a lot of benefit to using them. But while well-known JavaScript patterns are useful, another side of development could benefit from its own set of design patterns: jQuery plugins. The official jQuery plugin authoring guide (http://docs.jquery.com/Plugins/Authoring) offers a great starting point for getting into writing plugins and widgets, but let’s take it further.

Plugin development has evolved over the past few years. We no longer have just one way to write plugins, but many. In reality, certain patterns might work better for a particular problem or component than others.

Some developers may wish to use the jQuery UI widget factory (http://ajpiano.com/widgetfactory/); it’s great for complex, flexible UI components. Some may not. Some might like to structure their plugins more like modules (similar to the module pattern) or use a more formal module format such as AMD (asynchronous module definition) (https://github.com/amdjs/amdjs-api/wiki/AMD). Some might want their plugins to harness the power of prototypal inheritance. Some might want to use custom events or pub/sub to communicate from plugins to the rest of their app. And so on.

I began to think about plugin patterns after noticing a number of efforts to create a one-size-fits-all jQuery plugin boilerplate. While such a boilerplate is a great idea in theory, the reality is that we rarely write plugins in one fixed way, using a single pattern all the time.

Let’s assume that you’ve tried your hand at writing your own jQuery plugins at some point and you’re comfortable putting together something that works. It’s functional. It does what it needs to do, but perhaps you feel it could be structured better. Maybe it could be more flexible or could solve more issues. If this sounds familiar and you aren’t sure of the differences between many of the different jQuery plugin patterns, then you might find what I have to say helpful.

My advice won’t provide solutions to every possible pattern, but it will cover popular patterns that developers use in the wild.

Note: This post is targeted at intermediate to advanced developers. If you don’t feel you’re ready for this just yet, I’m happy to recommend the official jQuery Plugins/Authoring (http://docs.jquery.com/Plugins/Authoring) guide, Ben Alman’s plugin style guide (http://msdn.microsoft.com/en-us/scriptjunkie/ff696759) and Remy Sharp’s “Signs of a Poorly Written jQuery Plugin (http://remysharp.com/2010/06/03/signs-of-a-poorly-written-jquery-plugin/).”

Patterns

jQuery plugins have very few defined rules, which one of the reasons for the incredible diversity in how they’re implemented. At the most basic level, you can write a plugin simply by adding a new function property to jQuery’s $.fn object, as follows:

1 $.fn.myPluginName = function() {
2     // your plugin logic
3 };

This is great for compactness, but the following would be a better foundation to build on:

1 (function( $ ){
2   $.fn.myPluginName = function() {
3     // your plugin logic
4   };
5 })( jQuery );

Here, we’ve wrapped our plugin logic in an anonymous function. To ensure that our use of the $ sign as a shorthand creates no conflicts between jQuery and other JavaScript libraries, we simply pass it to this closure, which maps it to the dollar sign, thus ensuring that it can’t be affected by anything outside of its scope of execution.

An alternative way to write this pattern would be to use $.extend, which enables you to define multiple functions at once and which sometimes make more sense semantically:

1 (function( $ ){
2     $.extend($.fn, {
3         myplugin: function(){
4             // your plugin logic
5         }
6     });
7 })( jQuery );

We could do a lot more to improve on all of this; and the first complete pattern we’ll be looking at today, the lightweight pattern, covers some best practices that we can use for basic everyday plugin development and that takes into account common gotchas to look out for.

Some Quick Notes

You can find all of the patterns from this post in this GitHub repository (https://github.com/addyosmani/jquery-plugin-patterns/).

While most of the patterns below will be explained, I recommend reading through the comments in the code, because they will offer more insight into why certain practices are best.

I should also mention that none of this would be possible without the previous work, input and advice of other members of the jQuery community. I’ve listed them inline with each pattern so that you can read up on their individual work if interested.

A Lightweight Start

Let’s begin our look at patterns with something basic that follows best practices (including those in the jQuery plugin-authoring guide). This pattern is ideal for developers who are either new to plugin development or who just want to achieve something simple (such as a utility plugin). This lightweight start uses the following:

  • Common best practices, such as a semi-colon before the function’s invocation; window, document, undefined passed in as arguments; and adherence to the jQuery core style guidelines.
  • A basic defaults object.
  • A simple plugin constructor for logic related to the initial creation and the assignment of the element to work with.
  • Extending the options with defaults.
  • A lightweight wrapper around the constructor, which helps to avoid issues such as multiple instantiations.
01 /*!
02  * jQuery lightweight plugin boilerplate
03  * Original author: @ajpiano
04  * Further changes, comments: @addyosmani
05  * Licensed under the MIT license
06  */
07  
08 // the semi-colon before the function invocation is a safety
09 // net against concatenated scripts and/or other plugins
10 // that are not closed properly.
11 ;(function ( $, window, document, undefined ) {
12  
13     // undefined is used here as the undefined global
14     // variable in ECMAScript 3 and is mutable (i.e. it can
15     // be changed by someone else). undefined isn't really
16     // being passed in so we can ensure that its value is
17     // truly undefined. In ES5, undefined can no longer be
18     // modified.
19  
20     // window and document are passed through as local
21     // variables rather than as globals, because this (slightly)
22     // quickens the resolution process and can be more
23     // efficiently minified (especially when both are
24     // regularly referenced in your plugin).
25  
26     // Create the defaults once
27     var pluginName = 'defaultPluginName',
28         defaults = {
29             propertyName: "value"
30         };
31  
32     // The actual plugin constructor
33     function Plugin( element, options ) {
34         this.element = element;
35  
36         // jQuery has an extend method that merges the
37         // contents of two or more objects, storing the
38         // result in the first object. The first object
39         // is generally empty because we don't want to alter
40         // the default options for future instances of the plugin
41         this.options = $.extend( {}, defaults, options) ;
42  
43         this._defaults = defaults;
44         this._name = pluginName;
45  
46         this.init();
47     }
48  
49     Plugin.prototype.init = function () {
50         // Place initialization logic here
51         // You already have access to the DOM element and
52         // the options via the instance, e.g. this.element
53         // and this.options
54     };
55  
56     // A really lightweight plugin wrapper around the constructor,
57     // preventing against multiple instantiations
58     $.fn[pluginName] = function ( options ) {
59         return this.each(function () {
60             if (!$.data(this, 'plugin_' + pluginName)) {
61                 $.data(this, 'plugin_' + pluginName,
62                 new Plugin( this, options ));
63             }
64         });
65     }
66  
67 })( jQuery, window, document );

Further Reading

“Complete” Widget Factory

While the authoring guide is a great introduction to plugin development, it doesn’t offer a great number of conveniences for obscuring away from common plumbing tasks that we have to deal with on a regular basis.

The jQuery UI Widget Factory is a solution to this problem that helps you build complex, stateful plugins based on object-oriented principles. It also eases communication with your plugin’s instance, obfuscating a number of the repetitive tasks that you would have to code when working with basic plugins.

In case you haven’t come across these before, stateful plugins keep track of their current state, also allowing you to change properties of the plugin after it has been initialized.

One of the great things about the Widget Factory is that the majority of the jQuery UI library actually uses it as a base for its components. This means that if you’re looking for further guidance on structure beyond this template, you won’t have to look beyond the jQuery UI repository.

Back to patterns. This jQuery UI boilerplate does the following:

  • Covers almost all supported default methods, including triggering events.
  • Includes comments for all of the methods used, so that you’re never unsure of where logic should fit in your plugin.
01 /*!
02  * jQuery UI Widget-factory plugin boilerplate (for 1.8/9+)
03  * Author: @addyosmani
04  * Further changes: @peolanha
05  * Licensed under the MIT license
06  */
07  
08 ;(function ( $, window, document, undefined ) {
09  
10     // define your widget under a namespace of your choice
11     //  with additional parameters e.g.
12     // $.widget( "namespace.widgetname", (optional) - an
13     // existing widget prototype to inherit from, an object
14     // literal to become the widget's prototype );
15  
16     $.widget( "namespace.widgetname" , {
17  
18         //Options to be used as defaults
19         options: {
20             someValue: null
21         },
22  
23         //Setup widget (eg. element creation, apply theming
24         // , bind events etc.)
25         _create: function () {
26  
27             // _create will automatically run the first time
28             // this widget is called. Put the initial widget
29             // setup code here, then you can access the element
30             // on which the widget was called via this.element.
31             // The options defined above can be accessed
32             // via this.options this.element.addStuff();
33         },
34  
35         // Destroy an instantiated plugin and clean up
36         // modifications the widget has made to the DOM
37         destroy: function () {
38  
39             // this.element.removeStuff();
40             // For UI 1.8, destroy must be invoked from the
41             // base widget
42             $.Widget.prototype.destroy.call(this);
43             // For UI 1.9, define _destroy instead and don't
44             // worry about
45             // calling the base widget
46         },
47  
48         methodB: function ( event ) {
49             //_trigger dispatches callbacks the plugin user
50             // can subscribe to
51             // signature: _trigger( "callbackName" , [eventObject],
52             // [uiObject] )
53             // eg. this._trigger( "hover", e /*where e.type ==
54             // "mouseenter"*/, { hovered: $(e.target)});
55             this._trigger('methodA', event, {
56                 key: value
57             });
58         },
59  
60         methodA: function ( event ) {
61             this._trigger('dataChanged', event, {
62                 key: value
63             });
64         },
65  
66         // Respond to any changes the user makes to the
67         // option method
68         _setOption: function ( key, value ) {
69             switch (key) {
70             case "someValue":
71                 //this.options.someValue = doSomethingWith( value );
72                 break;
73             default:
74                 //this.options[ key ] = value;
75                 break;
76             }
77  
78             // For UI 1.8, _setOption must be manually invoked
79             // from the base widget
80             $.Widget.prototype._setOption.apply( this, arguments );
81             // For UI 1.9 the _super method can be used instead
82             // this._super( "_setOption", key, value );
83         }
84     });
85  
86 })( jQuery, window, document );

Further Reading

Namespacing And Nested Namespacing

Namespacing your code is a way to avoid collisions with other objects and variables in the global namespace. They’re important because you want to safeguard your plugin from breaking in the event that another script on the page uses the same variable or plugin names as yours. As a good citizen of the global namespace, you must also do your best not to prevent other developers’ scripts from executing because of the same issues.

JavaScript doesn’t really have built-in support for namespaces as other languages do, but it does have objects that can be used to achieve a similar effect. Employing a top-level object as the name of your namespace, you can easily check for the existence of another object on the page with the same name. If such an object does not exist, then we define it; if it does exist, then we simply extend it with our plugin.

Objects (or, rather, object literals) can be used to create nested namespaces, such as namespace.subnamespace.pluginName and so on. But to keep things simple, the namespacing boilerplate below should give you everything you need to get started with these concepts.

01 /*!
02  * jQuery namespaced 'Starter' plugin boilerplate
03  * Author: @dougneiner
04  * Further changes: @addyosmani
05  * Licensed under the MIT license
06  */
07  
08 ;(function ( $ ) {
09     if (!$.myNamespace) {
10         $.myNamespace = {};
11     };
12  
13     $.myNamespace.myPluginName = function ( el, myFunctionParam, options ) {
14         // To avoid scope issues, use 'base' instead of 'this'
15         // to reference this class from internal events and functions.
16         var base = this;
17  
18         // Access to jQuery and DOM versions of element
19         base.$el = $(el);
20         base.el = el;
21  
22         // Add a reverse reference to the DOM object
23         base.$el.data( "myNamespace.myPluginName" , base );
24  
25         base.init = function () {
26             base.myFunctionParam = myFunctionParam;
27  
28             base.options = $.extend({},
29             $.myNamespace.myPluginName.defaultOptions, options);
30  
31             // Put your initialization code here
32         };
33  
34         // Sample Function, Uncomment to use
35         // base.functionName = function( paramaters ){
36         //
37         // };
38         // Run initializer
39         base.init();
40     };
41  
42     $.myNamespace.myPluginName.defaultOptions = {
43         myDefaultValue: ""
44     };
45  
46     $.fn.mynamespace_myPluginName = function
47         ( myFunctionParam, options ) {
48         return this.each(function () {
49             (new $.myNamespace.myPluginName(this,
50             myFunctionParam, options));
51         });
52     };
53  
54 })( jQuery );

Further Reading

Custom Events For Pub/Sub (With The Widget factory)

You may have used the Observer (Pub/Sub) pattern in the past to develop asynchronous JavaScript applications. The basic idea here is that elements will publish event notifications when something interesting occurs in your application. Other elements then subscribe to or listen for these events and respond accordingly. This results in the logic for your application being significantly more decoupled (which is always good).

In jQuery, we have this idea that custom events provide a built-in means to implement a publish and subscribe system that’s quite similar to the Observer pattern. So, bind('eventType') is functionally equivalent to performing subscribe('eventType'), and trigger('eventType') is roughly equivalent to publish('eventType').

Some developers might consider the jQuery event system as having too much overhead to be used as a publish and subscribe system, but it’s been architected to be both reliable and robust for most use cases. In the following jQuery UI widget factory template, we’ll implement a basic custom event-based pub/sub pattern that allows our plugin to subscribe to event notifications from the rest of our application, which publishes them.

01 /*!
02  * jQuery custom-events plugin boilerplate
03  * Author: DevPatch
04  * Further changes: @addyosmani
05  * Licensed under the MIT license
06  */
07  
08 // In this pattern, we use jQuery's custom events to add
09 // pub/sub (publish/subscribe) capabilities to widgets.
10 // Each widget would publish certain events and subscribe
11 // to others. This approach effectively helps to decouple
12 // the widgets and enables them to function independently.
13  
14 ;(function ( $, window, document, undefined ) {
15     $.widget("ao.eventStatus", {
16         options: {
17  
18         },
19  
20         _create : function() {
21             var self = this;
22  
23             //self.element.addClass( "my-widget" );
24  
25             //subscribe to 'myEventStart'
26             self.element.bind( "myEventStart", function( e ) {
27                 console.log("event start");
28             });
29  
30             //subscribe to 'myEventEnd'
31             self.element.bind( "myEventEnd", function( e ) {
32                 console.log("event end");
33             });
34  
35             //unsubscribe to 'myEventStart'
36             //self.element.unbind( "myEventStart", function(e){
37                 ///console.log("unsubscribed to this event");
38             //});
39         },
40  
41         destroy: function(){
42             $.Widget.prototype.destroy.apply( this, arguments );
43         },
44     });
45 })( jQuery, window , document );
46  
47 //Publishing event notifications
48 //usage:
49 // $(".my-widget").trigger("myEventStart");
50 // $(".my-widget").trigger("myEventEnd");

Further Reading

Prototypal Inheritance With The DOM-To-Object Bridge Pattern

In JavaScript, we don’t have the traditional notion of classes that you would find in other classical programming languages, but we do have prototypal inheritance. With prototypal inheritance, an object inherits from another object. And we can apply this concept to jQuery plugin development.

Alex Sexton (http://alexsexton.com/) and Scott Gonzalez (http://scottgonzalez.com/) have looked at this topic in detail. In sum, they found that for organized modular development, clearly separating the object that defines the logic for a plugin from the plugin-generation process itself can be beneficial. The benefit is that testing your plugin’s code becomes easier, and you can also adjust the way things work behind the scenes without altering the way that any object APIs you’ve implemented are used.

In Sexton’s previous post on this topic, he implements a bridge that enables you to attach your general logic to a particular plugin, which we’ve implemented in the template below. Another advantage of this pattern is that you don’t have to constantly repeat the same plugin initialization code, thus ensuring that the concepts behind DRY development are maintained. Some developers might also find this pattern easier to read than others.

01 /*!
02  * jQuery prototypal inheritance plugin boilerplate
03  * Author: Alex Sexton, Scott Gonzalez
04  * Further changes: @addyosmani
05  * Licensed under the MIT license
06  */
07  
08 // myObject - an object representing a concept that you want
09 // to model (e.g. a car)
10 var myObject = {
11   init: function( options, elem ) {
12     // Mix in the passed-in options with the default options
13     this.options = $.extend( {}, this.options, options );
14  
15     // Save the element reference, both as a jQuery
16     // reference and a normal reference
17     this.elem  = elem;
18     this.$elem = $(elem);
19  
20     // Build the DOM's initial structure
21     this._build();
22  
23     // return this so that we can chain and use the bridge with less code.
24     return this;
25   },
26   options: {
27     name: "No name"
28   },
29   _build: function(){
30     //this.$elem.html('<h1>'+this.options.name+'</h1>');
31   },
32   myMethod: function( msg ){
33     // You have direct access to the associated and cached
34     // jQuery element
35     // this.$elem.append('<p>'+msg+'</p>');
36   }
37 };
38  
39 // Object.create support test, and fallback for browsers without it
40 if ( typeof Object.create !== 'function' ) {
41     Object.create = function (o) {
42         function F() {}
43         F.prototype = o;
44         return new F();
45     };
46 }
47  
48 // Create a plugin based on a defined object
49 $.plugin = function( name, object ) {
50   $.fn[name] = function( options ) {
51     return this.each(function() {
52       if ( ! $.data( this, name ) ) {
53         $.data( this, name, Object.create(object).init(
54         options, this ) );
55       }
56     });
57   };
58 };
59  
60 // Usage:
61 // With myObject, we could now essentially do this:
62 // $.plugin('myobj', myObject);
63  
64 // and at this point we could do the following
65 // $('#elem').myobj({name: "John"});
66 // var inst = $('#elem').data('myobj');
67 // inst.myMethod('I am a method');

Further Reading

jQuery UI Widget Factory Bridge

If you liked the idea of generating plugins based on objects in the last design pattern, then you might be interested in a method found in the jQuery UI Widget Factory called $.widget.bridge. This bridge basically serves as a middle layer between a JavaScript object that is created using $.widget and jQuery’s API, providing a more built-in solution to achieving object-based plugin definition. Effectively, we’re able to create stateful plugins using a custom constructor.

Moreover, $.widget.bridge provides access to a number of other capabilities, including the following:

  • Both public and private methods are handled as one would expect in classical OOP (i.e. public methods are exposed, while calls to private methods are not possible);
  • Automatic protection against multiple initializations;
  • Automatic generation of instances of a passed object, and storage of them within the selection’s internal $.data cache;
  • Options can be altered post-initialization.

For further information on how to use this pattern, look at the comments in the boilerplate below:

01 /*!
02  * jQuery UI Widget factory "bridge" plugin boilerplate
03  * Author: @erichynds
04  * Further changes, additional comments: @addyosmani
05  * Licensed under the MIT license
06  */
07  
08 // a "widgetName" object constructor
09 // required: this must accept two arguments,
10 // options: an object of configuration options
11 // element: the DOM element the instance was created on
12 var widgetName = function( options, element ){
13   this.name = "myWidgetName";
14   this.options = options;
15   this.element = element;
16   this._init();
17 }
18  
19 // the "widgetName" prototype
20 widgetName.prototype = {
21  
22     // _create will automatically run the first time this
23     // widget is called
24     _create: function(){
25         // creation code
26     },
27  
28     // required: initialization logic for the plugin goes into _init
29     // This fires when your instance is first created and when
30     // attempting to initialize the widget again (by the bridge)
31     // after it has already been initialized.
32     _init: function(){
33         // init code
34     },
35  
36     // required: objects to be used with the bridge must contain an
37     // 'option'. Post-initialization, the logic for changing options
38     // goes here.
39     option: function( key, value ){
40  
41         // optional: get/change options post initialization
42         // ignore if you don't require them.
43  
44         // signature: $('#foo').bar({ cool:false });
45         if( $.isPlainObject( key ) ){
46             this.options = $.extend( true, this.options, key );
47  
48         // signature: $('#foo').option('cool'); - getter
49         } else if ( key && typeof value === "undefined" ){
50             return this.options[ key ];
51  
52         // signature: $('#foo').bar('option', 'baz', false);
53         } else {
54             this.options[ key ] = value;
55         }
56  
57         // required: option must return the current instance.
58         // When re-initializing an instance on elements, option
59         // is called first and is then chained to the _init method.
60         return this;
61     },
62  
63     // notice no underscore is used for public methods
64     publicFunction: function(){
65         console.log('public function');
66     },
67  
68     // underscores are used for private methods
69     _privateFunction: function(){
70         console.log('private function');
71     }
72 };
73  
74 // usage:
75  
76 // connect the widget obj to jQuery's API under the "foo" namespace
77 // $.widget.bridge("foo", widgetName);
78  
79 // create an instance of the widget for use
80 // var instance = $("#elem").foo({
81 //     baz: true
82 // });
83  
84 // your widget instance exists in the elem's data
85 // instance.data("foo").element; // => #elem element
86  
87 // bridge allows you to call public methods...
88 // instance.foo("publicFunction"); // => "public method"
89  
90 // bridge prevents calls to internal methods
91 // instance.foo("_privateFunction"); // => #elem element

Further Reading

jQuery Mobile Widgets With The Widget factory

jQuery mobile is a framework that encourages the design of ubiquitous Web applications that work both on popular mobile devices and platforms and on the desktop. Rather than writing unique applications for each device or OS, you simply write the code once and it should ideally run on many of the A-, B- and C-grade browsers out there at the moment.

The fundamentals behind jQuery mobile can also be applied to plugin and widget development, as seen in some of the core jQuery mobile widgets used in the official library suite. What’s interesting here is that even though there are very small, subtle differences in writing a “mobile”-optimized widget, if you’re familiar with using the jQuery UI Widget Factory, you should be able to start writing these right away.

The mobile-optimized widget below has a number of interesting differences than the standard UI widget pattern we saw earlier:

  • $.mobile.widget is referenced as an existing widget prototype from which to inherit. For standard widgets, passing through any such prototype is unnecessary for basic development, but using this jQuery-mobile specific widget prototype provides internal access to further “options” formatting.
  • You’ll notice in _create() a guide on how the official jQuery mobile widgets handle element selection, opting for a role-based approach that better fits the jQM mark-up. This isn’t at all to say that standard selection isn’t recommended, only that this approach might make more sense given the structure of jQM pages.
  • Guidelines are also provided in comment form for applying your plugin methods on pagecreate as well as for selecting the plugin application via data roles and data attributes.
001 /*!
002  * (jQuery mobile) jQuery UI Widget-factory plugin boilerplate (for 1.8/9+)
003  * Author: @scottjehl
004  * Further changes: @addyosmani
005  * Licensed under the MIT license
006  */
007  
008 ;(function ( $, window, document, undefined ) {
009  
010     //define a widget under a namespace of your choice
011     //here 'mobile' has been used in the first parameter
012     $.widget( "mobile.widgetName", $.mobile.widget, {
013  
014         //Options to be used as defaults
015         options: {
016             foo: true,
017             bar: false
018         },
019  
020         _create: function() {
021             // _create will automatically run the first time this
022             // widget is called. Put the initial widget set-up code
023             // here, then you can access the element on which
024             // the widget was called via this.element
025             // The options defined above can be accessed via
026             // this.options
027  
028             //var m = this.element,
029             //p = m.parents(":jqmData(role='page')"),
030             //c = p.find(":jqmData(role='content')")
031         },
032  
033         // Private methods/props start with underscores
034         _dosomething: function(){ ... },
035  
036         // Public methods like these below can can be called
037                 // externally:
038         // $("#myelem").foo( "enable", arguments );
039  
040         enable: function() { ... },
041  
042         // Destroy an instantiated plugin and clean up modifications
043         // the widget has made to the DOM
044         destroy: function () {
045             //this.element.removeStuff();
046             // For UI 1.8, destroy must be invoked from the
047             // base widget
048             $.Widget.prototype.destroy.call(this);
049             // For UI 1.9, define _destroy instead and don't
050             // worry about calling the base widget
051         },
052  
053         methodB: function ( event ) {
054             //_trigger dispatches callbacks the plugin user can
055             // subscribe to
056             //signature: _trigger( "callbackName" , [eventObject],
057             //  [uiObject] )
058             // eg. this._trigger( "hover", e /*where e.type ==
059             // "mouseenter"*/, { hovered: $(e.target)});
060             this._trigger('methodA', event, {
061                 key: value
062             });
063         },
064  
065         methodA: function ( event ) {
066             this._trigger('dataChanged', event, {
067                 key: value
068             });
069         },
070  
071         //Respond to any changes the user makes to the option method
072         _setOption: function ( key, value ) {
073             switch (key) {
074             case "someValue":
075                 //this.options.someValue = doSomethingWith( value );
076                 break;
077             default:
078                 //this.options[ key ] = value;
079                 break;
080             }
081  
082             // For UI 1.8, _setOption must be manually invoked from
083             // the base widget
084             $.Widget.prototype._setOption.apply(this, arguments);
085             // For UI 1.9 the _super method can be used instead
086             // this._super( "_setOption", key, value );
087         }
088     });
089  
090 })( jQuery, window, document );
091  
092 //usage: $("#myelem").foo( options );
093  
094 /* Some additional notes - delete this section before using the boilerplate.
095  
096  We can also self-init this widget whenever a new page in jQuery Mobile is created. jQuery Mobile's "page" plugin dispatches a "create" event when a jQuery Mobile page (found via data-role=page attr) is first initialized.
097  
098 We can listen for that event (called "pagecreate" ) and run our plugin automatically whenever a new page is created.
099  
100 $(document).bind("pagecreate", function (e) {
101     // In here, e.target refers to the page that was created
102     // (it's the target of the pagecreate event)
103     // So, we can simply find elements on this page that match a
104     // selector of our choosing, and call our plugin on them.
105     // Here's how we'd call our "foo" plugin on any element with a
106     // data-role attribute of "foo":
107     $(e.target).find("[data-role='foo']").foo(options);
108  
109     // Or, better yet, let's write the selector accounting for the configurable
110     // data-attribute namespace
111     $(e.target).find(":jqmData(role='foo')").foo(options);
112 });
113  
114 That's it. Now you can simply reference the script containing your widget and pagecreate binding in a page running jQuery Mobile site, and it will automatically run like any other jQM plugin.
115  */

RequireJS And The jQuery UI Widget Factory

RequireJS is a script loader that provides a clean solution for encapsulating application logic inside manageable modules. It’s able to load modules in the correct order (through its order plugin); it simplifies the process of combining scripts via its excellent optimizer; and it provides the means for defining module dependencies on a per-module basis.

James Burke has written a comprehensive set of tutorials on getting started with RequireJS. But what if you’re already familiar with it and would like to wrap your jQuery UI widgets or plugins in a RequireJS-compatible module wrapper?.

In the boilerplate pattern below, we demonstrate how a compatible widget can be defined that does the following:

  • Allows the definition of widget module dependencies, building on top of the previous jQuery UI boilerplate presented earlier;
  • Demonstrates one approach to passing in HTML template assets for creating templated widgets with jQuery (in conjunction with the jQuery tmpl plugin) (View the comments in _create().)
  • Includes a quick tip on adjustments that you can make to your widget module if you wish to later pass it through the RequireJS optimizer
01 /*!
02  * jQuery UI Widget + RequireJS module boilerplate (for 1.8/9+)
03  * Authors: @jrburke, @addyosmani
04  * Licensed under the MIT license
05  */
06  
07 // Note from James:
08 //
09 // This assumes you are using the RequireJS+jQuery file, and
10 // that the following files are all in the same directory:
11 //
12 // - require-jquery.js
13 // - jquery-ui.custom.min.js (custom jQuery UI build with widget factory)
14 // - templates/
15 //    - asset.html
16 // - ao.myWidget.js
17  
18 // Then you can construct the widget like so:
19  
20 //ao.myWidget.js file:
21 define("ao.myWidget", ["jquery", "text!templates/asset.html", "jquery-ui.custom.min","jquery.tmpl"], function ($, assetHtml) {
22  
23     // define your widget under a namespace of your choice
24     // 'ao' is used here as a demonstration
25     $.widget( "ao.myWidget", {
26  
27         // Options to be used as defaults
28         options: {},
29  
30         // Set up widget (e.g. create element, apply theming,
31         // bind events, etc.)
32         _create: function () {
33  
34             // _create will automatically run the first time
35             // this widget is called. Put the initial widget
36             // set-up code here, then you can access the element
37             // on which the widget was called via this.element.
38             // The options defined above can be accessed via
39             // this.options
40  
41             //this.element.addStuff();
42             //this.element.addStuff();
43             //this.element.tmpl(assetHtml).appendTo(this.content);
44         },
45  
46         // Destroy an instantiated plugin and clean up modifications
47         // that the widget has made to the DOM
48         destroy: function () {
49             //t his.element.removeStuff();
50             // For UI 1.8, destroy must be invoked from the base
51             // widget
52             $.Widget.prototype.destroy.call( this );
53             // For UI 1.9, define _destroy instead and don't worry
54             // about calling the base widget
55         },
56  
57         methodB: function ( event ) {
58             // _trigger dispatches callbacks the plugin user can
59             // subscribe to
60             //signature: _trigger( "callbackName" , [eventObject],
61             // [uiObject] )
62             this._trigger('methodA', event, {
63                 key: value
64             });
65         },
66  
67         methodA: function ( event ) {
68             this._trigger('dataChanged', event, {
69                 key: value
70             });
71         },
72  
73         //Respond to any changes the user makes to the option method
74         _setOption: function ( key, value ) {
75             switch (key) {
76             case "someValue":
77                 //this.options.someValue = doSomethingWith( value );
78                 break;
79             default:
80                 //this.options[ key ] = value;
81                 break;
82             }
83  
84             // For UI 1.8, _setOption must be manually invoked from
85             // the base widget
86             $.Widget.prototype._setOption.apply( this, arguments );
87             // For UI 1.9 the _super method can be used instead
88             //this._super( "_setOption", key, value );
89         }
90  
91         //somewhere assetHtml would be used for templating, depending
92         // on your choice.
93     });
94 });
95  
96 // If you are going to use the RequireJS optimizer to combine files
97 // together, you can leave off the "ao.myWidget" argument to define:
98 // define(["jquery", "text!templates/asset.html", "jquery-ui.custom.min"], …

Further Reading

Globally And Per-Call Overridable Options (Best Options Pattern)

For our next pattern, we’ll look at an optimal approach to configuring options and defaults for your plugin. The way you’re probably familiar with defining plugin options is to pass through an object literal of defaults to $.extend, as demonstrated in our basic plugin boilerplate.

If, however, you’re working with a plugin with many customizable options that you would like users to be able to override either globally or on a per-call level, then you can structure things a little differently.

Instead, by referring to an options object defined within the plugin namespace explicitly (for example, $fn.pluginName.options) and merging this with any options passed through to the plugin when it is initially invoked, users have the option of either passing options through during plugin initialization or overriding options outside of the plugin (as demonstrated here).

01 /*!
02  * jQuery 'best options' plugin boilerplate
03  * Author: @cowboy
04  * Further changes: @addyosmani
05  * Licensed under the MIT license
06  */
07  
08 ;(function ( $, window, document, undefined ) {
09  
10     $.fn.pluginName = function ( options ) {
11  
12         // Here's a best practice for overriding 'defaults'
13         // with specified options. Note how, rather than a
14         // regular defaults object being passed as the second
15         // parameter, we instead refer to $.fn.pluginName.options
16         // explicitly, merging it with the options passed directly
17         // to the plugin. This allows us to override options both
18         // globally and on a per-call level.
19  
20         options = $.extend( {}, $.fn.pluginName.options, options );
21  
22         return this.each(function () {
23  
24             var elem = $(this);
25  
26         });
27     };
28  
29     // Globally overriding options
30     // Here are our publicly accessible default plugin options
31     // that are available in case the user doesn't pass in all
32     // of the values expected. The user is given a default
33     // experience but can also override the values as necessary.
34     // eg. $fn.pluginName.key ='otherval';
35  
36     $.fn.pluginName.options = {
37  
38         key: "value",
39         myMethod: function ( elem, param ) {
40  
41         }
42     };
43  
44 })( jQuery, window, document );

Further Reading

A Highly Configurable And Mutable Plugin

Like Alex Sexton’s pattern, the following logic for our plugin isn’t nested in a jQuery plugin itself. We instead define our plugin’s logic using a constructor and an object literal defined on its prototype, using jQuery for the actual instantiation of the plugin object.

Customization is taken to the next level by employing two little tricks, one of which you’ve seen in previous patterns:

  • Options can be overridden both globally and per collection of elements;
  • Options can be customized on a per-element level through HTML5 data attributes (as shown below). This facilitates plugin behavior that can be applied to a collection of elements but then customized inline without the need to instantiate each element with a different default value.

You don’t see the latter option in the wild too often, but it can be a significantly cleaner solution (as long as you don’t mind the inline approach). If you’re wondering where this could be useful, imagine writing a draggable plugin for a large set of elements. You could go about customizing their options like this:

1 javascript
2 $('.item-a').draggable({'defaultPosition':'top-left'});
3 $('.item-b').draggable({'defaultPosition':'bottom-right'});
4 $('.item-c').draggable({'defaultPosition':'bottom-left'});
5 //etc

But using our patterns inline approach, the following would be possible:

1 javascript
2 $('.items').draggable();
1 html
2 <li class="item" data-plugin-options='{"defaultPosition":"top-left"}'></div>
3 <li class="item" data-plugin-options='{"defaultPosition":"bottom-left"}'></div>

And so on. You may well have a preference for one of these approaches, but it is another potentially useful pattern to be aware of.

01 /*
02  * 'Highly configurable' mutable plugin boilerplate
03  * Author: @markdalgleish
04  * Further changes, comments: @addyosmani
05  * Licensed under the MIT license
06  */
07  
08 // Note that with this pattern, as per Alex Sexton's, the plugin logic
09 // hasn't been nested in a jQuery plugin. Instead, we just use
10 // jQuery for its instantiation.
11  
12 ;(function( $, window, document, undefined ){
13  
14   // our plugin constructor
15   var Plugin = function( elem, options ){
16       this.elem = elem;
17       this.$elem = $(elem);
18       this.options = options;
19  
20       // This next line takes advantage of HTML5 data attributes
21       // to support customization of the plugin on a per-element
22       // basis. For example,
23       // <div class=item' data-plugin-options='{"message":"Goodbye World!"}'></div>
24       this.metadata = this.$elem.data( 'plugin-options' );
25     };
26  
27   // the plugin prototype
28   Plugin.prototype = {
29     defaults: {
30       message: 'Hello world!'
31     },
32  
33     init: function() {
34       // Introduce defaults that can be extended either
35       // globally or using an object literal.
36       this.config = $.extend({}, this.defaults, this.options,
37       this.metadata);
38  
39       // Sample usage:
40       // Set the message per instance:
41       // $('#elem').plugin({ message: 'Goodbye World!'});
42       // or
43       // var p = new Plugin(document.getElementById('elem'),
44       // { message: 'Goodbye World!'}).init()
45       // or, set the global default message:
46       // Plugin.defaults.message = 'Goodbye World!'
47  
48       this.sampleMethod();
49       return this;
50     },
51  
52     sampleMethod: function() {
53       // eg. show the currently configured message
54       // console.log(this.config.message);
55     }
56   }
57  
58   Plugin.defaults = Plugin.prototype.defaults;
59  
60   $.fn.plugin = function(options) {
61     return this.each(function() {
62       new Plugin(this, options).init();
63     });
64   };
65  
66   //optional: window.Plugin = Plugin;
67  
68 })( jQuery, window , document );

Further Reading

AMD- And CommonJS-Compatible Modules

While many of the plugin and widget patterns presented above are acceptable for general use, they aren’t without their caveats. Some require jQuery or the jQuery UI Widget Factory to be present in order to function, while only a few could be easily adapted to work well as globally compatible modules both client-side and in other environments.

For this reason, a number of developers, including me, CDNjs (http://cdnjs.com) maintainer Thomas Davis (https://github.com/thomasdavis) and RP Florence (https://github.com/rpflorence), have been looking at both the AMD (https://github.com/amdjs/amdjs-api/wiki/AMD) (Asynchronous Module Definition) and CommonJS (http://wiki.commonjs.org/wiki/Modules) module specifications in the hopes of extending boilerplate plugin patterns to cleanly work with packages and dependencies. John Hann (http://twitter.com/unscriptable) and Kit Cambridge (https://gist.github.com/1251221) have also explored work in this area.

AMD

The AMD module format (a specification for defining modules where both the module and dependencies can be asynchronously loaded) has a number of distinct advantages, including being both asynchronous and highly flexible by nature, thus removing the tight coupling one commonly finds between code and module identity. It’s considered a reliable stepping stone to the module system (http://wiki.ecmascript.org/doku.php?id=harmony:modules) proposed for ES Harmony.

When working with anonymous modules, the idea of a module’s identity is DRY, making it trivial to avoid duplication of file names and code. Because the code is more portable, it can be easily moved to other locations without needing to alter the code itself. Developers can also run the same code in multiple environments just by using an AMD optimizer that works with a CommonJS environment, such as r.js.

With AMD, the two key concepts you need to be aware of are the require method and the define method, which facilitate module definition and dependency loading. The define method is used to define named or unnamed modules based on the specification, using the following signature:

1 define(module_id /*optional*/, [dependencies], definition function /*function for instantiating the module or object*/);

As you can tell from the inline comments, the module’s ID is an optional argument that is typically required only when non-AMD concatenation tools are being used (it could be useful in other edge cases, too). One of the benefits of opting not to use module IDs is having the flexibility to move your module around the file system without needing to change its ID. The module’s ID is equivalent to folder paths in simple packages and when not used in packages.

The dependencies argument represents an array of dependencies that are required by the module you are defining, and the third argument (factory) is a function that’s executed to instantiate your module. A barebones module could be defined as follows:

01 // Note: here, a module ID (myModule) is used for demonstration
02 // purposes only
03  
04 define('myModule', ['foo', 'bar'], function ( foo, bar ) {
05     // return a value that defines the module export
06     // (i.e. the functionality we want to expose for consumption)
07     return function () {};
08 });
09  
10 // A more useful example, however, might be:
11 define('myModule', ['math', 'graph'], function ( math, graph ) {
12     return {
13             plot: function(x, y){
14                     return graph.drawPie(math.randomGrid(x,y));
15             }
16     };
17 });

The require method, on the other hand, is typically used to load code in a top-level JavaScript file or in a module should you wish to dynamically fetch dependencies. Here is an example of its usage:

01 // Here, the 'exports' from the two modules loaded are passed as
02 // function arguments to the callback
03  
04 require(['foo', 'bar'], function ( foo, bar ) {
05         // rest of your code here
06 });
07  
08 // And here's an AMD-example that shows dynamically loaded
09 // dependencies
10  
11 define(function ( require ) {
12     var isReady = false, foobar;
13  
14     require(['foo', 'bar'], function (foo, bar) {
15         isReady = true;
16         foobar = foo() + bar();
17     });
18  
19     // We can still return a module
20     return {
21         isReady: isReady,
22         foobar: foobar
23     };
24 });

The above are trivial examples of just how useful AMD modules can be, but they should provide a foundation that helps you understand how they work. Many big visible applications and companies currently use AMD modules as a part of their architecture, including IBM (http://www.ibm.com) and the BBC iPlayer (http://www.bbc.co.uk/iplayer/). The specification has been discussed for well over a year in both the Dojo and CommonJS communities, so it’s had time to evolve and improve. For more reasons on why many developers are opting to use AMD modules in their applications, you may be interested in James Burke’s article “On Inventing JS Module Formats and Script Loaders (http://tagneto.blogspot.com/2011/04/on-inventing-js-module-formats-and.html).”

Shortly, we’ll look at writing globally compatible modules that work with AMD and other module formats and environments, something that offers even more power. Before that, we need to briefly discuss a related module format, one with a specification by CommonJS.

CommonJS

In case you’re not familiar with it, CommonJS (http://www.commonjs.org/) is a volunteer working group that designs, prototypes and standardizes JavaScript APIs. To date, it’s attempted to ratify standards for modules (http://www.commonjs.org/specs/modules/1.0/) and packages (http://wiki.commonjs.org/wiki/Packages/1.0). The CommonJS module proposal specifies a simple API for declaring modules server-side; but, as John Hann correctly states, there are really only two ways to use CommonJS modules in the browser: either wrap them or wrap them.

What this means is that we can either have the browser wrap modules (which can be a slow process) or at build time (which can be fast to execute in the browser but requires a build step).

Some developers, however, feel that CommonJS is better suited to server-side development, which is one reason for the current disagreement over which format should be used as the de facto standard in the pre-Harmony age moving forward. One argument against CommonJS is that many CommonJS APIs address server-oriented features that one would simply not be able to implement at the browser level in JavaScript; for example, io>, system and js could be considered unimplementable by the nature of their functionality.

That said, knowing how to structure CommonJS modules is useful so that we can better appreciate how they fit in when defining modules that might be used everywhere. Modules that have applications on both the client and server side include validation, conversion and templating engines. The way some developers choose which format to use is to opt for CommonJS when a module can be used in a server-side environment and to opt for AMD otherwise.

Because AMD modules are capable of using plugins and can define more granular things such as constructors and functions, this makes sense. CommonJS modules are able to define objects that are tedious to work with only if you’re trying to obtain constructors from them.

From a structural perspective, a CommonJS module is a reusable piece of JavaScript that exports specific objects made available to any dependent code; there are typically no function wrappers around such modules. Plenty of great tutorials on implementing CommonJS modules are out there, but at a high level, the modules basically contain two main parts: a variable named exports, which contains the objects that a module makes available to other modules, and a require function, which modules can use to import the exports of other modules.

01 // A very basic module named 'foobar'
02 function foobar(){
03         this.foo = function(){
04                 console.log('Hello foo');
05         }
06  
07         this.bar = function(){
08                 console.log('Hello bar');
09         }
10 }
11  
12 exports.foobar = foobar;
13  
14 // An application using 'foobar'
15  
16 // Access the module relative to the path
17 // where both usage and module files exist
18 // in the same directory
19  
20 var foobar = require('./foobar').foobar,
21     test   = new foobar.foo();
22  
23 test.bar(); // 'Hello bar'

There are a number of great JavaScript libraries for handling module loading in AMD and CommonJS formats, but my preference is RequireJS (http://requirejs.org) (curl.js (https://github.com/unscriptable/curl) is also quite reliable). Complete tutorials on these tools are beyond the scope of this article, but I recommend John Hann’s post “curl.js: Yet Another AMD Loader (http://unscriptable.com/index.php/2011/03/30/curl-js-yet-another-amd-loader/),” and James Burke’s post “
LABjs and RequireJS: Loading JavaScript Resources the Fun Way (http://msdn.microsoft.com/en-us/scriptjunkie/ff943568).”

With what we’ve covered so far, wouldn’t it be great if we could define and load plugin modules compatible with AMD, CommonJS and other standards that are also compatible with different environments (client-side, server-side and beyond)? Our work on AMD and UMD (Universal Module Definition) plugins and widgets is still at a very early stage, but we’re hoping to develop solutions that can do just that.

One such pattern we’re working on (https://github.com/addyosmani/jquery-plugin-patterns/issues/1) at the moment appears below, which has the following features:

  • A core/base plugin is loaded into a $.core namespace, which can then be easily extended using plugin extensions via the namespacing pattern. Plugins loaded via script tags automatically populate a plugin namespace under core (i.e. $.core.plugin.methodName()).
  • The pattern can be quite nice to work with because plugin extensions can access properties and methods defined in the base or, with a little tweaking, override default behavior so that it can be extended to do more.
  • A loader isn’t necessarily required at all to make this pattern fully function.

usage.html

01 <script type="text/javascript" src="http://code.jquery.com/jquery-1.6.4.min.js"></script>
02 <script type="text/javascript" src="pluginCore.js"></script>
03 <script type="text/javascript" src="pluginExtension.js"></script>
04  
05 <script type="text/javascript">
06  
07 $(function(){
08  
09     // Our plugin 'core' is exposed under a core namespace in
10     // this example, which we first cache
11     var core = $.core;
12  
13     // Then use use some of the built-in core functionality to
14     // highlight all divs in the page yellow
15     core.highlightAll();
16  
17     // Access the plugins (extensions) loaded into the 'plugin'
18     // namespace of our core module:
19  
20     // Set the first div in the page to have a green background.
21     core.plugin.setGreen("div:first");
22     // Here we're making use of the core's 'highlight' method
23     // under the hood from a plugin loaded in after it
24  
25     // Set the last div to the 'errorColor' property defined in
26     // our core module/plugin. If you review the code further down,
27     // you'll see how easy it is to consume properties and methods
28     // between the core and other plugins
29     core.plugin.setRed('div:last');
30 });
31  
32 </script>

pluginCore.js

01 // Module/Plugin core
02 // Note: the wrapper code you see around the module is what enables
03 // us to support multiple module formats and specifications by
04 // mapping the arguments defined to what a specific format expects
05 // to be present. Our actual module functionality is defined lower
06 // down, where a named module and exports are demonstrated.
07 //
08 // Note that dependencies can just as easily be declared if required
09 // and should work as demonstrated earlier with the AMD module examples.
10  
11 (function ( name, definition ){
12   var theModule = definition(),
13       // this is considered "safe":
14       hasDefine = typeof define === 'function' && define.amd,
15       // hasDefine = typeof define === 'function',
16       hasExports = typeof module !== 'undefined' && module.exports;
17  
18   if ( hasDefine ){ // AMD Module
19     define(theModule);
20   } else if ( hasExports ) { // Node.js Module
21     module.exports = theModule;
22   } else { // Assign to common namespaces or simply the global object (window)
23     (this.jQuery || this.ender || this.$ || this)[name] = theModule;
24   }
25 })( 'core', function () {
26     var module = this;
27     module.plugins = [];
28     module.highlightColor = "yellow";
29     module.errorColor = "red";
30  
31   // define the core module here and return the public API
32  
33   // This is the highlight method used by the core highlightAll()
34   // method and all of the plugins highlighting elements different
35   // colors
36   module.highlight = function(el,strColor){
37     if(this.jQuery){
38       jQuery(el).css('background', strColor);
39     }
40   }
41   return {
42       highlightAll:function(){
43         module.highlight('div', module.highlightColor);
44       }
45   };
46  
47 });

pluginExtension.js

01 // Extension to module core
02  
03 (function ( name, definition ) {
04     var theModule = definition(),
05         hasDefine = typeof define === 'function',
06         hasExports = typeof module !== 'undefined' && module.exports;
07  
08     if ( hasDefine ) { // AMD Module
09         define(theModule);
10     } else if ( hasExports ) { // Node.js Module
11         module.exports = theModule;
12     } else { // Assign to common namespaces or simply the global object (window)
13  
14         // account for for flat-file/global module extensions
15         var obj = null;
16         var namespaces = name.split(".");
17         var scope = (this.jQuery || this.ender || this.$ || this);
18         for (var i = 0; i < namespaces.length; i++) {
19             var packageName = namespaces[i];
20             if (obj && i == namespaces.length - 1) {
21                 obj[packageName] = theModule;
22             } else if (typeof scope[packageName] === "undefined") {
23                 scope[packageName] = {};
24             }
25             obj = scope[packageName];
26         }
27  
28     }
29 })('core.plugin', function () {
30  
31     // Define your module here and return the public API.
32     // This code could be easily adapted with the core to
33     // allow for methods that overwrite and extend core functionality
34     // in order to expand the highlight method to do more if you wish.
35     return {
36         setGreen: function ( el ) {
37             highlight(el, 'green');
38         },
39         setRed: function ( el ) {
40             highlight(el, errorColor);
41         }
42     };
43  
44 });

While this is beyond the scope of this article, you may have noticed that different types of require methods were mentioned when we discussed AMD and CommonJS.

The concern with a similar naming convention is, of course, confusion, and the community is currently split on the merits of a global require function. John Hann’s suggestion here is that rather than call it require, which would probably fail to inform users of the difference between a global and inner require, renaming the global loader method something else might make more sense (such as the name of the library). For this reason, curl.js uses curl, and RequireJS uses requirejs.

This is probably a bigger discussion for another day, but I hope this brief walkthrough of both module types has increased your awareness of these formats and has encouraged you to further explore and experiment with them in your apps.

Further Reading

What Makes A Good jQuery Plugin?

At the end of the day, patterns are just one aspect of plugin development. And before we wrap up, here are my criteria for selecting third-party plugins, which will hopefully help developers write them.

Quality
Do your best to adhere to best practices with both the JavaScript and jQuery that you write. Are your solutions optimal? Do they follow the jQuery core style guidelines (http://docs.jquery.com/JQuery_Core_Style_Guidelines)? If not, is your code at least relatively clean and readable?

Compatibility
Which versions of jQuery is your plugin compatible with? Have you tested it with the latest builds? If the plugin was written before jQuery 1.6, then it might have issues with attributes, because the way we approach them changed with that release. New versions of jQuery offer improvements and opportunities for the jQuery project to improve on what the core library offers. With this comes occasional breakages (mainly in major releases) as we move towards a better way of doing things. I’d like to see plugin authors update their code when necessary or, at a minimum, test their plugins with new versions to make sure everything works as expected.

Reliability
Your plugin should come with its own set of unit tests. Not only do these prove your plugin actually works, but they can also improve the design without breaking it for end users. I consider unit tests essential for any serious jQuery plugin that is meant for a production environment, and they’re not that hard to write. For an excellent guide to automated JavaScript testing with QUnit, you may be interested in “Automating JavaScript Testing With QUnit (http://msdn.microsoft.com/en-us/scriptjunkie/gg749824),” by Jorn Zaefferer (http://bassistance.de/).

Performance
If the plugin needs to perform tasks that require a lot of computing power or that heavily manipulates the DOM, then you should follow best practices that minimize this. Use jsPerf.com (http://jsperf.com) to test segments of your code so that you’re aware of how well it performs in different browsers before releasing the plugin.

Documentation
If you intend for other developers to use your plugin, ensure that it’s well documented. Document your API. What methods and options does the plugin support? Does it have any gotchas that users need to be aware of? If users cannot figure out how to use your plugin, they’ll likely look for an alternative. Also, do your best to comment the code. This is by far the best gift you could give to other developers. If someone feels they can navigate your code base well enough to fork it or improve it, then you’ve done a good job.

Likelihood of maintenance
When releasing a plugin, estimate how much time you’ll have to devote to maintenance and support. We all love to share our plugins with the community, but you need to set expectations for your ability to answer questions, address issues and make improvements. This can be done simply by stating your intentions for maintenance in the README file, and let users decide whether to make fixes themselves.

Conclusion

Today, we’ve explored several time-saving design patterns and best practices that can be employed to improve your plugin development process. Some are better suited to certain use cases than others, but I hope that the code comments that discuss the ins and outs of these variations on popular plugins and widgets were useful.

Remember, when selecting a pattern, be practical. Don’t use a plugin pattern just for the sake of it; rather, spend some time understanding the underlying structure, and establish how well it solves your problem or fits the component you’re trying to build. Choose the pattern that best suits your needs.

And that’s it. If there’s a particular pattern or approach you prefer taking to writing plugins which you feel would benefit others (which hasn’t been covered), please feel free to stick it in a gist (http://gist.github.com) and share it in the comments below. I’m sure it would be appreciated.

Until next time, happy coding!

Thanks to John Hann, Julian Aubourg, Andree Hanson and everyone else who reviewed this post for their comments and feedback.

Dec 13

Post Info

tags

Comments are closed.