I find myself increasingly using jQuery as my JavaScript framework of choice.

It’s by-line of “write less, do more” really seems apt.

But sometimes, by writing just that little bit extra, you can do even more.

For example, I often try to do the following:

• Make most jQuery code into reusable plugins
• Use the jQuery plugin development pattern for added flexibility
• Use QUnit to unit test JavaScript
• Combine the two approaches to drive out a richer API for the plugin

By unit testing with QUnit, I find I often need to trigger additional events or add additional code from within the plugin so the test can be meaningful.

But this extra code isn’t only useful for testing, it becomes a useful part of the plugin’s API, improving its functionality and flexibility without sacrificing maintainability and readability of the code.

I’ll try to demonstrate that in this post.

Make most of your jQuery code into reusable plugins

In many cases, where there is a block of jQuery code initializing something, it is a candidate for a plugin.

It took me a little while before I gave jquery plugins a go, thinking it will be complex and I won’t have time. But, it turns out to be really simple, elegant and useful for both simple and complicated scenarios.

Example to create a dynamic side note toggler

Lets take a simple example for illustration: suppose I have some HTML that acts as an aside, or side note, and that I want to toggle its appearance.

Lets say we agree this kind of HTML format for it (or microformat):

<p>Some text before the side note.</p>

<div class="side-note">
	<p>Any HTML could go here including</p>
	<ul>
		<li>Bulleted lists</li>
		<li>Tabular data</li>
		<li>Images</li>
	</ul>

	<div class="side-note">
		<p>Even nested side notes, if that is of any use!</p>
	</div>
</div>

<p>Some text after the side note.</p>

The first way I’d do it might be something like this:

$(document).ready(function() {
    $('.side-note').each(function() {
        $(this)
            .addClass('dynamic-side-note')
            .hide()
            .wrap('<div class="dynamic-side-note-container"></div>')
            .before('<h3 class="toggler"><a href="#">Side note:</a></h3>')
            .parent(0).find('> h3.toggler > a').click(function() {
                $(this).parents('.dynamic-side-note-container').eq(0).find('> .dynamic-side-note').slideToggle();
                return false;
            });
    });
});

I could have added a click event handler to the h3 header above, but using an anchor adds keyboard accessibility.

(The CSS selector could also be improved, e.g. to narrow it down to only side-notes in some content div, e.g. $('#content .side-note').)

Here is a working example

As a simple jQuery plugin

The above works. But, we can move most of the above code into a jQuery plugin.

Why bother? We can gain a bit more flexibility, such as the ability to use any selector, not rely on a side-note class. We could pass in other parameters such as what the text for the side note toggler/header should be, etc.

As a first attempt, the plugin might look something like this:

$.fn.sideNotes = function() {
    // returning this way allows chaining
    return $(this)
        .addClass('dynamic-side-note')
        .hide()
        .wrap('<div class="dynamic-side-note-container"></div>')
        .before('<h3 class="toggler"><a href="#">Side note:</a></h3>')
        .parent(0).find('> h3.toggler > a').click(function() {
            $(this).parents('.dynamic-side-note-container').eq(0).find('> .dynamic-side-note').slideToggle();
            return false;
        });
};

We then just need to invoke the plugin:

jQuery(function() {
    $('.side-note').sideNotes();
});

(Note how you could use any selector now not just .side-note as above.)

Here is a working example using the simple plugin

Plugins also make it easier to pass in more options for configuration. The next example uses a useful pattern for plugin development that also shows a nice way to handle plugin options:

Use the jQuery plugin development pattern for added flexibility

The post, A Plugin Development Pattern (for jQuery), from the Learning jQuery blog is really useful.

It provides a good way to write plugins that also get the following features:

• Configurability by passing in options
• Default options to keep invoking code small and neat
• A closure where you split your code out into manageable private functions, etc., if you need
• Ensuring that your plugin support chaining
• And more

Using some of those ideas, here is what we might come up with for the sideNotes plugin:

(function($) {
    $.fn.sideNotes = function(options) {

    // build main options before element iteration by extending the default ones
    var opts = $.extend({}, $.fn.sideNotes.defaults, options);

    // for each side note, do the magic.
    return $(this)
        .hide()
        .wrap('<div class="dynamic-side-note"></div>')
        .before('<h3 class="toggler"><a href="#">' + opts.sideNoteToggleText +'</a></h3>')
        .parent(0).find('> h3.toggler > a').click(function() {
            $(this).parents('.dynamic-side-note').eq(0).find('> .side-note').slideToggle();
            return false;
        });
    };

    // plugin defaults
    $.fn.sideNotes.defaults = {
        sideNoteToggleText : 'Side note:'
    };
})(jQuery);

And invoking the plugin is the same as before:

jQuery(function() {
    $('.side-note').sideNotes();

    // or overriding the default side note toggle text:
    // $('.side-note').sideNotes({ sideNoteToggleText : 'As an aside:' });
});

Here is a working example using the plugin pattern

Unit testing the jQuery plugin

As the plugin code is reasonably well encapsulated, we can create some unit tests for this plugin.

Unit testing jQuery (as with any code) gives you confidence in maintaining it. For example, when refactoring code, unit tests give you confidence that you can do it without breaking things. Plugins, almost by definition are good candidates for unit testing.

Examples of unit tests for this plugin

Our example side note plugin is quite simple, so the unit tests will likely be small in number. Types of tests we might include are the following:

• Test that we can expand/collapse a side note
• Test that we can expand/collapse a side note many times and ensure the toggle state reported is correct each time
• Test that when the side note plugin has run, all the side notes are collapsed initially
• Test that we can change the toggle text to something else

And so on.

Remember, the unit tests should not test the slideToggle() method we happened to use (as that should be unit tested itself, and we may use other ways of toggling the side note in the future). Instead, we just need to unit test our code and plugin functionality.

So ideally, we might even want to “mock” the slideToggle(), if necessary.

Use QUnit to unit test JavaScript

QUnit is a unit testing framework, used internally by jQuery itself for all its core JavaScript, and now opened up and documented for others to use, too. It is a simple framework to support the creation and execution of tests.

The tests are run in a browser. You could automate it against all your target browsers by using something like Selenium.

The framework is in its early days (a setup and teardown set of methods would be nice, for example), but is rich enough to get started with it.

Here is a QUnit test page for the side note plugin

(I included a manual test area as this can sometimes be useful where visual confirmation is useful or automated tests of some parts is not possible/easy. Having this all in one place can be handy.)

Using unit tests and plugins helps create a richer API for the plugin

To write testable code, you may find you need to provide more hooks in the code. Yet, you probably don’t want to pollute your code so much that it is detrimental to performance or maintainability.

Triggering events on the plugin for added flexibility

In the unit test example page, how did we manage to get unit tests to confirm a side note had been toggled when we didn’t have any callback for it?

The first idea people might have is to pass a callback that a plugin user can point to in the options when invoking the plugin, something like this:

jQuery(function() {
    $('.side-note').sideNotes(
        {
            toggled : function() { console.log('side note was toggled'); }
        }
    );
});

That looks useful; the unit test can provide a callback when it invokes the plugin.

However, that limits us to just one observer, the one that invoked the side note plugin in the first place.

But we can go one step further: trigger events. This allows more than one observer to watch for the event. This is achieved using jQuery’s trigger() and bind() methods.

By having unit tests watching for these events, it does not distort the plugin code; it enhances its API making the event useful for a real plugin user, if they need it.

In our side note plugin example, when we call slideToggle() we can trigger an event when the toggling has completed:

// all the stuff that gets to the
// slide toggle bit comes here!
.slideToggle( function() {
    $(this).trigger('sideNoteToggled');
});

If your code cares when this happens, you can bind to this event, something like this:

$('.side-note').bind('sideNoteToggled', eventHandlerGoesHere);

(A fuller example below uses trigger() to also pass the expanded/collapsed state in conjunction with some ARIA information.)

Providing default implementations that can be replaced (or mocked for unit testing)

One particular challenge I had with unit testing this side note example was that the slideToggle() method used by the plugin, internally runs asynchronously (using setTimeout etc).

Writing normal unit test code means the test can finish before the animation has run.

Even though I tried to use setTimeout() on the tests themselves to try and make them wait for the sideNote to finish toggling, and passing in the fastest speed possible to the slideToggle method, it wasn’t always right, and not consistent across all browsers.

This gave me the opportunity to do a few things:

• Encapsulate the call to slideToggle in another method
• Make that method the default implementation, but overrideable
• Use this to provide a mock slide toggler for testing purposes

With jQuery’s plugin architecture providing a default implementation is quite straight forward:

$.fn.sideNotes.toggle = function() {
    $(this).slideToggle(function() {
        $(this).trigger('sideNoteToggled');
    });
};

Mocking the slideToggle() call is nice because we don’t want to test external code in our unit tests; that should have been unit tested by whoever wrote that (the jQuery team I imagine! I’ll have to look at their unit tests when I get a moment to see how they overcome asynchronous issue — there is some mechanism to provide stop() and start() methods for AJAX testing and I tried this here, but still wasn’t getting consistent results).

In our example, we can overwrite the the default toggle method to simply use toggle() instead of slideToggle(), which is a non-animated version that runs and completes immediately.

This makes writing the testing code a bit simpler too. (There are one or two bits that I did that didn’t feel too great in my opinion, such as the way I chose to expose the post toggle action, but that is perhaps for another day to sort out!)

To override the default implementation, you can redefine sideNotes.toggle in your code, something like this:

$.fn.sideNotes.toggle = function() {
    $(this).toggle().trigger('sideNoteToggled');
};

Example QUnit test code

So taking the above considerations this is what we might have in our QUnit unit test code:

This code block shows a test util object to help instrument the test, and then at the bottom, an example of a mock object to replace the slideToggle() call.

(function(){
    var testUtils = {
        isExpandedCount : 0,
        isCollapsedCount : 0,
        
        defaultTestOptions : {
            selector : '#example .side-note',
            sideNoteOptions : {},
            speed : 'fast'
        },
        
        // a crude setup like method, which QUnit currently doesn't have
        init : function(options) {
            testUtils.reset();
    
            var opts = $.extend({ sideNoteOptions : {} }, testUtils.defaultTestOptions, options);
    
            // tests assume the relevant HTML is present on the page the test is running
            $(opts.selector)
                .bind('sideNoteToggled', testUtils.sideNoteToggled)
                    .sideNotes(opts.sideNoteOptions);
            
            return $(opts.selector);
        },
        
        sideNoteToggled : function(event, isExpanded) {
            isExpanded ? testUtils.isExpandedCount++ : testUtils.isCollapsedCount++;
            
            $(event.target).trigger('sideNoteToggleCaptured');
        },
        
        // until there is an explicit tear down method this will have to do
        reset : function() {
            $('#example .side-note').unbind('sideNoteToggled');
            testUtils.isExpandedCount = 0;
            testUtils.isCollapsedCount = 0;
        }
    };

    // mock the slideToggle. We are not testing that.
    function mockSideNoteToggle() {
        $(this).toggle();
        
        $.fn.sideNotes.toggled.call(this);
    }
    
    // keep the original implementation if we want to use it later
    $.fn.sideNotes.originalToggler = $.fn.sideNotes.toggle;

    // override the default toggle method with the mock
    $.fn.sideNotes.toggle = mockSideNoteToggle;
})();

We can then write unit tests, such as this one (note this code would go inside the anonymous function used above):

module("Single toggle tests");

test("Test side note is expanded when toggled", function() {
    var $sideNote = testUtils.init();

    $sideNote.each(function() {
        equals($(this).attr('aria-expanded'), 'false', "Side not starts as collapsed");
    });
    
    $('#example')
        .find('.side-note:eq(0)').bind('sideNoteToggleCaptured', function() {
            equals(testUtils.isExpandedCount, 1, "A node has been expanded");
            equals(testUtils.isCollapsedCount, 0, "No nodes have been collapsed after initialization");
            equals(this['aria-expanded'], true, "Node’s aria state is expanded");
        })
        .end()
            .find('.toggler > a:eq(0)').click();
            // calling click() is like simulating the user action to start the test
});

In the above example, the following is happening:

1. The call to init() creates/initializes the sideNote plugin
2. We then assert that the ARIA state reports each side note is not expanded
3. We then find each side note and bind to the sideNoteToggleCaptured event (which is raised by the unit test utility shown earlier, not by the plugin itself)
4. We then simulate a user action by finding the toggler and clicking it
5. The simulated click() makes the plugin eventually trigger the sideNoteToggled event, which the testUtils object will catch.
6. The test util will catch that event and update the various testing counters and itself trigger the sideNoteToggleCaptured event.
7. Finally at this point, we can run our assertions, such as confirming the expected number of times the side note was expanded/collapsed and what the expected ARIA state should be (in this example seen by the use of the equals() function).

See the full example for more unit tests

The additional tests in the full example also show the side note being dynamically created per test run, so you don’t always have to have the HTML set up exactly as needed for every test, manually.

The unit test code in that example can probably be further improved by refactoring those test() functions into a helper function where you pass in callbacks to run when the test has completed, how many clicks you want to invoke, etc, but that is for another time!

Final plugin code

Here is the final plugin code (with some additional options not discussed above):

(function($) {
    $.fn.sideNotes = function(options) {

        // build main options before element iteration
        var opts = $.extend({}, $.fn.sideNotes.defaults, options);

        // iterate and process each matched element
        return $(this)
            .addClass('dynamic-side-note').hide()
            .attr('aria-expanded', false)
            .wrap('<div class="dynamic-side-note-container"></div>')
            .before('<' + opts.toggleElement + '><a class="toggler" href="#">' + opts.sideNoteToggleText +'</a></' + opts.toggleElement + '>')
            .parent(0)
                .find(opts.toggleElement + '.toggler > a')
                    .click(doToggle);

        // example of private method
        function doToggle() {
            $(this)
                .parents('.dynamic-side-note-container').eq(0)
                    .find('> .dynamic-side-note').each( function() {
                        $.fn.sideNotes.toggle.call(this, options);
                    });

            return false;
        }
    };

    // plugin defaults
    $.fn.sideNotes.defaults = {
        sideNoteToggleText : 'Side note:',
        speed : 'normal',
        toggleElement : 'h3'
    };

    // default implementation for the toggler (public. i.e. overrideable)
    $.fn.sideNotes.toggle = function(options) {
        $(this).slideToggle(options.speed, $.fn.sideNotes.toggled);
    };

    // default callback when toggle completed (public. i.e. overrideable)
    $.fn.sideNotes.toggled = function() {
        this['aria-expanded'] = this['aria-expanded'] === true ? false : true;

        $(this).trigger('sideNoteToggled', this['aria-expanded']);
    };
})(jQuery);

Is the additional lines of code for a plugin worth it?

The plugin used in the unit tested example is larger in terms of lines of code than the very first attempt, above.

In this case, the lines of code is still quite small, and as plugins get even larger the percentage difference is likely to be small (the size difference is more noticeable in smaller code samples, such as this contrived side note example).

Minimizing and gzipping JavaScript, plus using far future expires header for better caching would further reduce the percentage difference in file sizes of the two approaches.

Depending on your needs, this may be a reasonable trade-off in return for additional flexibility.

Summary

So, in many cases, jQuery code can be made reusable by making it into a plugin. Any time you find yourself writing a block of code, say inside a $(document).ready() block, consider converting it into a plugin and calling it.

When making the plugin, consider the following:

• Provide various options for flexibility
• Write unit tests to test your plugin
• Trigger important events inside your plugin to aide unit testability, and in doing so, increase flexibility of your plugin even more.

When you get the hang of this, it is probably better to write the unit tests before the actual plugin code. This will help focus on what is needed and what the plugin needs to expose in terms of capability. To be honest, at times I have found it easier to retrofit a plugin with unit tests. I probably need to be a bit more disciplined to write tests first!

(While there are a number of enhancements that could be added to this, the main thing I’d probably do is rename the plugin to something more generic than just a side note toggler, but I will leave that for the reader to do, and remember to refactor the unit tests accordingly!)

Hope that is useful?