Tom's Blog » Javascript

Unit testing your Javascript: Just Do It

Tom — Tue, 15 Dec 2009 20:26:12 +0000

Nike’s slogan is the only one fit for the issue I’m about to raise in this article: Unit testing. Deep down, everyone knows the benefits from unit testing your code. Unit testing can give you that warm feeling when you go to bed, knowing that the changes you made, didn’t break previously working code. It makes you happy and it gives you confidence.

Yet, a lot of us (including me) don’t actually start unit testing our code. There are a number of reasons for that, but I’ll have none of that now. Because now, I’m going to show you just how easy it is to unit test your Javascript. I’ll be using QUnit, made by John Resig, creator of jQuery. Even though I’ve just begun using QUnit, the code I presented in my previous three blog posts, has really benefitted greatly from it.

Setting up the environment

To set up your basic unit testing environment, you won’t need to go through a lot of trouble. It’s as easy as creating an HTML page which loads the latest jQuery instance, QUnit instance and a stylesheet.



    
        
        Tag library Unit Tests
        
        
        
    
    
        Tag library Unit Tests

At this point, nothing much will be shown when you run the HTML file in your browser, as we still have to add our unit tests.

Environment without tests

Adding Unit Tests

Now that you’ve seen how easy it is to set up your testing environment, it’s time to actually write a test. I will provide you with some samples from what I’ve used to test the Tag Javascript library. If you need an API, or you want to know all the possibilities, just head over to the QUnit website.

To keep my stuff organized, I try to reflect the regular structure as much as possible in my tests. This is what I mean:

File structure

All tests are in separate files, reflecting the original structure. The tests for /tag/tag.pubsub.js are in the file /tests/tag/tag.pubsub.js. I think it’s a good idea to keep your testing in modules. One big file, or even in the environment HTML file would also work. It’s just not that easy to work with if you have a lot of tests.

Since I’m all for the modular way, first thing we add is an indication that a new module is tested

$(function(){
    /**
     * Define the module:
     */
    module("Tag base class");
});

This goes in the file /tests/tag.js (see image above), and will be referenced in the HTML environment we set up as our first step:



    
        
        Tag library Unit Tests
        
        
        
 
        
        
        
    
    
        Tag library Unit Tests

In the environment, we first include the file containing the code to be tested. Next we include the file containing the tests for that code. You can add other files for each plugin you want to test.

Ok, our module is defined. The first test I’m adding is to verify if the file was loaded, and if the Tag namespace is defined in the window scope.

    /**
     * Define the module:
     */
    module("Tag base class");
 
    /**
     * Verify existence of the Tag object:
     */
    test("Tag", function() {
        expect(2); // optional
        equals(typeof window.Tag, "object", "Verifying existence of Tag object");
        equals(typeof window.Tag.constructor, "function", "Verifying constructor type");
    });

The tests to verify the existence of the Tag object are grouped inside a single test() case. Inside the test case, we can have as many assertions as we want. Here I have added 2 assertions: I verify if the type of window.Tag is an object, and if the constructor is a function. If both these assertions succeed, then that’s enough proof for me that the Tag base class is loaded and available on the page.

The basic premise of unit testing is that you test the smallest unit that makes up your code. In the case of the Tag library, the smallest unit will be a method from a plugin or the base class. So the next thing we’re obviously going to do, is test each of the methods inside the Tag object.

As an example, here are the assertions I’ve written to test the extend() functionality of Tag:

    /**
     * Verify working of extend method:
     */
    test("Tag.extend()",function() {
        // an assertion using ok()
        ok(typeof window.Tag.extend === "function","Method exists");
 
        // a dummy temporary plugin (also called a mock)
        var tmp = {
            _initCheck:false,
            init:function() {
                this._initCheck = true;
            }
        };
 
        // Verify reserved namespaces:
        var reserved = ["extFN", "extLocalFN"];
        $.each(reserved, function() {
            ok(!window.Tag.extend(this,tmp), "Namespace '" + this + "' cannot be overwritten");
        });
 
        // add test plugin
        ok(window.Tag.extend("test",tmp), "Namespace 'test' taken");
        ok(!window.Tag.extend("test",tmp), "Namespace 'test' cannot be taken twice");
        equals(typeof window.Tag.test, "object", "Tag.test plugin exists");
        equals(typeof window.Tag.fn.test, "object", "Test plugin added to FN");
 
        // verify if plugin is extended with extra functionality:
        $.each(reserved, function(index, ns) {
            var obj = window.Tag[ns];
 
            $.each(obj,function(key, value){
                same(window.Tag.test[key], obj[key], "Verified existence of '" + key + "'");
            });
        });
 
        // verify if init() was called:
        equals(true, window.Tag.test._initCheck, "Init was run");
    });

The extend() method does a lot of things, naturally, all these things need to be tested. It’s the only way to be sure that the method does what it promises to do. For complex methods, with lots of execution paths, it will become difficult to test everything. That’s a reason to keep your methods small, and work with subroutines: they’re just easier to test (and to understand half a year after you last touched that part of the code).

Unit testing AJAX calls

The Tag.core plugin has functionality to asynchronously load javascript files. The problem with AJAX is that it is asynchronous, while unit testing is synchronous. The tests will all be executed in order, no test will run in parallel with another test. Yet we still need to be able to test asynchronous calls. QUnit provides us with the asyncTest() method for this purpose. I haven’t used that method though, it’s possible to do it “manually”.

We just need to pause the chain of tests before our asynchronous test. Once that test is completed, we can resume the rest of the tests. This is basically just waiting for an asynchronous test to complete, so all things considered, we test an asynchronous test synchronously. Nothing will happen in parallel.

    /**
     * Verify working of loadJS method:
     */
    test("Tag.core.loadJS()",function() {
        // verify loading:
        window.Tag.core.loadJS("dummy.js");
        // when testing asynchronous functionality, we must temporarily stop the
        // running of the tests:
        stop();
        window.setTimeout(function(){
            equals(typeof window.dummy, "object", "Verifying existence of loaded dummy");
            // start the rest of the tests:
            start();
        },250);
    });

First, the chain of tests is paused via the stop() method. As soon as the test is done, the start() method will resume the normal chain of events. Simple but effective.

The asyncTest() method from QUnit does exactly the same as we have done here. It just executes the stop() method for you. You only need to indicate when to resume the tests.

Beware, an asynchronous test may only contain 1 asynchronous call. E.g. not executing 2 AJAX calls in 1 test but rather just 1. The test itself can contain multiple assertions.

    test("Tag.core.loadJS() multiple",function() {
        // verify loading multiple:
        window.Tag.core.loadJS(["dummy.js","dummy2.js"]);
        stop();
        window.setTimeout(function(){
            equals(typeof window.dummy, "object", "Verifying existence of loaded dummy");
            equals(typeof window.dummy2, "object", "Verifying existence of loaded second dummy");
            // start the rest of the tests:
            start();
        },250);
    });

The test results

While writing tests, you will want to see some results. Just save your files, and open the environment HTML file in your browser. The tests will be run, and you’ll be presented with the results:

Complete results, no errors

All failed assertions are marked in red. Any test can be clicked to see in a more detailed manner which assertions had what response:

Suite with errors and detail

If you provided meaningful descriptions in your tests, it should be easy to see where an assertion failed.

Conclusion

Unit testing your Javascript functionality couldn’t be made easier. Getting started shouldn’t be the threshold, it’s as easy as creating one HTML file. Writing tests can be a bit of an adventure. At first you’ll probably make some mistakes, but that’s okay. The more you write tests, the more efficient you’ll make them. But you have to start somewhere. Just practice.

Remember, I can only show you the door. You have to walk through it.

All code from previous three blog posts now has a complete coverage from unit tests. You can still see the code at my Codaset repository. Please, feel free to download, fork, comment, …

Building your own Javascript library (part 3)

Tom — Wed, 02 Dec 2009 16:59:34 +0000

Goal

In this final part of the series, I’m going to create a Publish/Subscribe provider for my new framework. With this so-called pubsub provider, it will be possible for any function to create or fire an event. Any other function may then listen for that event, and will get triggered when the event occurs. My main goal is to make sure that this provider is easy to use, not only for plugins, but also for regular functionality. Besides that, I also want to have my code as loosely coupled as possible. For that, I’m going to use a little bit of Dependency Injection + lazy loading. All this to make sure that plugins are as agnostic as possible about the outside world. If you want to know more, please read on!

Updates to the base library

I’m going to start with some amends to the functionality I have already created in the first part of the series. Don’t know if you remember, but there I created functionality that is copied inside each plugin that registers itself into the base class. One of these methods is called “toString”. During my testing, I have discovered that using that name is not such a good idea. When using Firebug, the “toString” method is constantly called when logging a method. That’s why I decided to rename the method to “_toString”.

Besides the name change, I have also added a local cache in the method. This is to make sure that the expensive for loop is executed only once. The result is then put in a local cache. On each subsequent call of “_toString”, the local cache is used.

(function($){
    if (typeof window.Tag == "undefined"){
        var Tag = window.Tag = function(){
            // We have a dependency on jQuery:
            if (typeof $ === "undefined" || $ !== window.jQuery){
                alert("Please load jQuery library first");
            }
 
            /*
             * @var Object - Contains all plugins
             */
            this.fn = {};
 
            /**
             * Basic extend functionality. Each new plugin should extend
             * the TAG library, and become part of its namespace
             *
             * @param namespace String - Namespace of the new plugin
             * @param obj Object - The new plugin
             *
             * @return void
             */
            this.extend = function(namespace,obj){
                if (typeof this[namespace] == "undefined"){
                    if (typeof this.fn[namespace] === "undefined" && typeof this[namespace] === "undefined"){
                        // extend each namespace with core functionality
                        $.extend(obj,this.fn.extFN);
 
                        // load the new plugin in the namespaces:
                        this.fn[namespace] = obj;
                        this[namespace] = this.fn[namespace];
 
                        // initialize the new library if necessary
                        if (typeof this[namespace].init === "function"){
                            this[namespace].init();
                        }
                    } else {
                        alert("The namespace '" + namespace + "' is already taken...");
                    }
                }
            };
 
            /**
             * Recursively set values in an object
             *
             * Method allows to set individual settings, without overwriting
             * existing other values in the settings.
             *
             * @param object Object - The object to modify
             * @param data Object - New values for settings
             *
             * @return Object - Current plugin for chainability
             */
            this.setObjectData = function(object, data) {
               var path = (typeof arguments[2] !== "undefined")?arguments[2]:[];
               for(var k in data){
                  path.push(k);
                  if (typeof data[k] === "object"){
                      this.setObjectData(object, data[k], path);
                  } else {
                      var tmpObject = object;
                      for(var i=0,l=path.length;i<l-1;i++){
                          tmpObject = tmpObject[path[i]];
                      }
                      tmpObject[k] = data[k];
                  }
               }
            };
        };
        window.Tag = new Tag();
 
        window.Tag.extFN = window.Tag.fn.extFN = {
            /*
             * @var Object - Cache object
             */
            _cache:{},
 
            /**
             * Set the settings of a plugin
             *
             * @param settings Object - New values for settings
             *
             * @return Object - Current plugin for chainability
             */
            setConfig:function(settings) {
               window.Tag.setObjectData(this.settings, settings);
               return this;
            },
 
            /**
             * Automagically determines correct name of a plugin
             *
             * @return String
             */
            _toString:function() {
                // Because a loop is costly, we'll only do it once, and cache
                // the result of the loop
                if (typeof this._cache['_toString'] === 'undefined') {
                    // the name is not cached, so we need to cache it:
                    this._cache['_toString'] = '';
                    for(var k in window.Tag.fn) {
                        if (window.Tag.fn[k] === this) {
                            this._cache['_toString'] = 'Tag.' + k;
                            break;
                        }
                    }
                }
 
                // notify the user that this is an unknown plugin
                if (this._cache['_toString'] === '') {
                    alert('Could not determine the name of the plugin');
                }
 
                // return the cached name:
                return this._cache['_toString'];
            }
        };
    }
})(jQuery);

While I was busy refactoring the “toString” method, I added a “getParent” method too. This method should be used when you want to refer to the Tag base class from within a plugin, without having to know the name. The advantage is that when Tag gets renamed, the plugins still need very little change in their code.

            //... inside the extFN part of the base object:
 
            /**
             * Returns the base object
             *
             * @return Object
             */
            getParent:function() {
                return window.Tag;
            },

For such a small method, I’m not going to repeat the entire base class again. Saves me some space, because this will be a long article

Creating the Pubsub plugin

Now for the new code. We start of with our basic template again:

(function(){
    var pubsub = {
        /**
         * @var object settings - The configuration of this library
         */
        settings:{}
    };
 
    // Let's put this in the 'pubsub' namespace of TAG:
    Tag.extend("pubsub",pubsub);
})();

Here I do need the settings. It will be filled up a bit later. A Pubsub provider will have 3 basic methods. In other implementations, they may have different names than what I’ll use, but that’s not very important. The methods I need are these:

A method to listen for an event: “subscribe”
A method to stop listening for an event: “unsubscribe”
A method to fire off an event: “notify”

I’ll start with subscribing to an event. The premise here is that a method registers itself as a listener for a particular event. So I need to know: what event? what should happen when that event occurs?

I have to keep track of that information. For this purpose, I’m going to create 2 properties in the plugin: One for keeping track of what method should be called on what event. And another one to make sure a subscription can easily be undone.

(function(){
    var pubsub = {
        /*
         * @var Object - Contains all subscriptions
         */
        subscriptions:{},
 
        /*
         * @var Object - Contains all subscription ID's
         */
        subscriptionIDs:[],
 
        /**
         * @var object settings - The configuration of this library
         */
        settings:{
            separator:'.'
        },
 
        /**
         * Create a subscription to a given notification
         *
         * @param plugin String - Name of the plugin that will send out the notification
         * @param evt String - Name of the notifiation event
         * @param fn Function - Callback function to be executed on notification
         *
         * @return integer - The id of the subscription
         */
        subscribe:function(plugin, evt, fn){
            var path = this._constructPath([plugin, evt]);
            if (typeof this.subscriptions[path] === 'undefined') {
                this.subscriptions[path] = [];
            }
 
            this.subscriptions[path].push(fn);
            this.subscriptionIDs.push({
                path:path,
                index:(this.subscriptions[path].length - 1)
            });
 
            return (this.subscriptionIDs.length - 1);
        },
 
        /**
         * Construct a path from the arguments
         *
         * @return String
         */
        _constructPath:function(list) {
            return list.join(this.settings.separator);
        }
    };
 
    // Let's put this in the 'pubsub' namespace of TAG:
    Tag.extend("pubsub",pubsub);
})();

Let me walk you through the code. The properties for keeping track are added and I have introduced a setting. This setting will be used in the method “_constructPath”. The “subscribe” method is added, and takes 3 parameters: the plugin that will fire the event, the event name, and the function that should be executed when that event takes place.

First, I create a ‘path’ from the plugin name and the event name. If the plugin is ‘Tag.autosuggest’, and the event is ‘gotResponse’, then the path will be ‘Tag.autosuggest.gotResponse’. I have created a method just to create the path. If I ever find out that the path should change, then I only need to change it in that one method. That’s called keeping your code DRY.

Second, the properties are filled up with the necessary data. Each path will be stored in the “subscriptions” property, along with a list of functions that will be executed when that event occurs. If two listeners subscribe to an event, then the index of that event will have a list of 2 functions.

Third, to make it’s easy to unsubscribe from an event, a second list is kept. Each subscription gets an entry in that list. The index of that subscription is then returned at the end of the “subscribe” method. With this ID, it’s possible to unsubscribe without having to specify the plugin and event.

(function(){
    var pubsub = {
        /*
         * @var Object - Contains all subscriptions
         */
        subscriptions:{},
 
        /*
         * @var Object - Contains all subscription ID's
         */
        subscriptionIDs:[],
 
        /**
         * @var object settings - The configuration of this library
         */
        settings:{
            separator:'.'
        },
 
        /**
         * Create a subscription to a given notification
         *
         * @param plugin String - Name of the plugin that will send out the notification
         * @param evt String - Name of the notifiation event
         * @param fn Function - Callback function to be executed on notification
         *
         * @return integer - The id of the subscription
         */
        subscribe:function(plugin, evt, fn){
            var path = this._constructPath([plugin, evt]);
            if (typeof this.subscriptions[path] === 'undefined') {
                this.subscriptions[path] = [];
            }
 
            this.subscriptions[path].push(fn);
            this.subscriptionIDs.push({
                path:path,
                index:(this.subscriptions[path].length - 1)
            });
 
            return (this.subscriptionIDs.length - 1);
        },
 
        /**
         * Cancels a subscription to a given notification
         *
         * @param id Integer - ID of the subscription
         *
         * @return Object - Pubsubhub plugin for chainability
         */
        unsubscribe:function(id) {
            if (typeof this.subscriptionIDs[id] !== "undefined" && this.subscriptionIDs[id] !== null) {
                // don't remove it with splice, or other id's will be FUBAR
                this.subscriptions[this.subscriptionIDs[id].path][this.subscriptionIDs[id].index] = null;
                this.subscriptionIDs[id] = null;
            } else {
                alert('Unable to remove this subscription');
            }
            return this;
        },
 
        /**
         * Construct a path from the arguments
         *
         * @return String
         */
        _constructPath:function(list) {
            return list.join(this.settings.separator);
        }
    };
 
    // Let's put this in the 'pubsub' namespace of TAG:
    Tag.extend("pubsub",pubsub);
})();

The “unsubscribe” method removes the entries from our lists. Via the given ID, it looks up where the callback function is listed in the “subscriptions” property. It is very important that we don’t physically remove the entry from the array. Instead, I just overwrite what was there with “null” values.

If we remove the entries via “Array.splice”, then the array will be re-indexed. This will invalidate all other ID’s, so we can’t use “Array.splice”. Using the regular “delete” method…. well, let’s just say that in this case it would work, but I’m not too fond of using “delete” with arrays. It doesn’t actually delete the entry, it just writes null values to that index. Yeah, that’s exactly what I’m doing manually. But that’s not called “deleting an entry”, so let’s make sure we don’t get confused. We don’t want to end up refactoring “delete” with “Array.splice”, because we forgot that we don’t want an actual delete.

(function(){
    var pubsub = {
        /*
         * @var Object - Contains all subscriptions
         */
        subscriptions:{},
 
        /*
         * @var Object - Contains all subscription ID's
         */
        subscriptionIDs:[],
 
        /**
         * @var object settings - The configuration of this library
         */
        settings:{
            separator:'.'
        },
 
        /**
         * Create a subscription to a given notification
         *
         * @param plugin String - Name of the plugin that will send out the notification
         * @param evt String - Name of the notifiation event
         * @param fn Function - Callback function to be executed on notification
         *
         * @return integer - The id of the subscription
         */
        subscribe:function(plugin, evt, fn){
            var path = this._constructPath([plugin, evt]);
            if (typeof this.subscriptions[path] === 'undefined') {
                this.subscriptions[path] = [];
            }
 
            this.subscriptions[path].push(fn);
            this.subscriptionIDs.push({
                path:path,
                index:(this.subscriptions[path].length - 1)
            });
 
            return (this.subscriptionIDs.length - 1);
        },
 
        /**
         * Cancels a subscription to a given notification
         *
         * @param id Integer - ID of the subscription
         *
         * @return Object - Pubsubhub plugin for chainability
         */
        unsubscribe:function(id) {
            if (typeof this.subscriptionIDs[id] !== "undefined" && this.subscriptionIDs[id] !== null) {
                // don't remove it with splice, or other id's will be FUBAR
                this.subscriptions[this.subscriptionIDs[id].path][this.subscriptionIDs[id].index] = null;
                this.subscriptionIDs[id] = null;
            } else {
                alert('Unable to remove this subscription');
            }
            return this;
        },
 
        /**
         * Send out a notification to all subscribers
         *
         * @param plugin String - Name fo the plugin
         * @param evt String - Name of the event
         *
         * @return Object - Pubsubhub plugin for chainability
         */
        notify:function(plugin, evt) {
            var path = this._constructPath([plugin, evt]);
            if (typeof this.subscriptions[path] !== 'undefined') {
                for(var i=0,l=this.subscriptions[path].length;i<l;i++){
                    // make sure we only execute functions, not strings, integers, null's, ...
                    if (typeof this.subscriptions[path][i] === 'function') {
                        this.subscriptions[path][i]();
                    }
                }
            }
        },
 
        /**
         * Construct a path from the arguments
         *
         * @return String
         */
        _constructPath:function(list) {
            return list.join(this.settings.separator);
        }
    };
 
    // Let's put this in the 'pubsub' namespace of TAG:
    Tag.extend("pubsub",pubsub);
})();

With the “notify” method, you fire off an event. There are two arguments: name of the plugin and name of the event. From these two arguments, the path is constructed again. Then I look up in the “subscriptions” list if that entry exists. If it does, then all functions listed there will be executed.

The “notify” method works as a fire-and-forget system. If there are no listeners for an event, then nothing will happen. There is no communication back to the method that fired the event. That’s not necessary. It’s not its task to know if the event will be correctly dispatched.

At the moment, “notify” doesn’t transmit a payload to the subscribers. I’m sure I will need that functionality eventually. I’ll add it later, when the need is actually there.

The problem of scope

When a method subscribes to an event, and then gets executed, there will be a problem with the scope of the method. The Pubsub plugin doesn’t know anything about the callback function, other than it is a function. It can either be an anonymous function, or it can be part of an object. Pubsub doesn’t know. Hence, when the function is called, there won’t be a scope. The scope is the function itself. For an anonymous function, that’s good. For a method that’s part of an object, that’s not good

Possible solution 1: Just execute the callback in the scope of the Pubsub provider, like this:

// ...
this.subscriptions[path][i].call(this);
// ...

This is not a good solution, because anonymous functions suddenly have a scope and methods from an object suddenly have a scope that isn’t theirs. If the method is ‘Tag.autosuggest.updateSuggestions’, then the scope should be ‘Tag.autosuggest’, and not ‘Tag.pubsub’.

Possible solution 2: Execute the callback in the scope of the notifier. Via some code, it should be easy to determine the scope of the notifier. But again, my same objections apply as with the first solution: Anonymous functions shouldn’t have a scope, and I don’t want to change the scope of methods from an existing object

Possible (and accepted) solution 3: Make sure the callback already has the correct scope before executing it. (see below)

Hitching a ride

(I told you this was going to be a long article) The idea comes from “dojo.hitch”: Via another method making sure that a given function is executed in a given scope. So I created “Tag.core.hitch” for this purpose. The name comes from Dojo, and the implementation is derived from dojo’s implementation.

        // inside the Tag.core plugin:
        /**
         * Runs fn in the given scope
         *
         * @param scope Object - The scope fn should run in
         * @param fn Function|String - The function to run
         *
         * Extra parameters are optional, and will be passed on to fn
         *
         * @return Function
         */
        hitch:function(scope, fn) {
            // arguments looks like an Array, but is an Object
            // here we convert it to an array
            var args = Array.prototype.slice.call(arguments);
            if (typeof scope === 'undefined' || typeof fn === 'undefined') {
                // both scope & fn should be defined
                alert('Tag.hitch: both scope and function should be defined');
                return null;
            }
            if(typeof fn === 'string'){
                if (typeof scope[fn] === 'undefined') {
                    alert('The function is not defined inside the given scope');
                    return null;
                }
                return function(){ return scope[fn].apply(scope, args.slice(2)); };
            }
            return function(){ return fn.apply(scope, args.slice(2)); };
        }

This method returns an anonymous function. Inside that anonymous function, the scope of the given function is set to the scope that’s defined in the arguments. Quite simple actually. But very effective.

With the hitch method, a subscriber is now in charge of making sure that the callback function is executed in the correct scope.

Dependency Injection

Before I come to the usage examples, there is one more thing I’d like to implement. You know how I like keeping my plugins agnostic. Well, instead of letting a plugin use the pubsub provider like this: “Tag.pubsub.notify(…)”, I want to make sure that it’s not important that the pubsub provider is called “Tag.pubsub”. In fact, if someone comes along and writes a better provider, it should be possible to use that provider without having to change the code of the plugins.

This can be accomplished with a little Dependency Injection. (DI via getters and setters to be precise). I’ll extend core plugin with 2 methods: “getPubsubProvider” and “setPubsubProvider”. With the getter, the Pubsub provider is returned. Via he setter it’s possible to specify another Pubsub provider. As the icing on the cake, I’ll add some lazy loading: if no pubsub provider is specified, then “getPubsubProvider” defaults to “Tag.pubsub”.

(function($){
    if (typeof window.Tag == "undefined"){
        var Tag = window.Tag = function(){
            // We have a dependency on jQuery:
            if (typeof $ === "undefined" || $ !== window.jQuery){
                alert("Please load jQuery library first");
            }
 
            /*
             * @var Object - Contains all plugins
             */
            this.fn = {};
 
            /**
             * Basic extend functionality. Each new plugin should extend
             * the TAG library, and become part of its namespace
             *
             * @param namespace String - Namespace of the new plugin
             * @param obj Object - The new plugin
             *
             * @return void
             */
            this.extend = function(namespace,obj){
                if (typeof this[namespace] == "undefined"){
                    if (typeof this.fn[namespace] === "undefined" && typeof this[namespace] === "undefined"){
                        // extend each namespace with core functionality
                        $.extend(obj,this.fn.extFN);
 
                        // load the new plugin in the namespaces:
                        this.fn[namespace] = obj;
                        this[namespace] = this.fn[namespace];
 
                        // initialize the new library if necessary
                        if (typeof this[namespace].init === "function"){
                            this[namespace].init();
                        }
                    } else {
                        alert("The namespace '" + namespace + "' is already taken...");
                    }
                }
            };
 
            /**
             * Recursively set values in an object
             *
             * Method allows to set individual settings, without overwriting
             * existing other values in the settings.
             *
             * @param object Object - The object to modify
             * @param data Object - New values for settings
             *
             * @return Object - Current plugin for chainability
             */
            this.setObjectData = function(object, data) {
               var path = (typeof arguments[2] !== "undefined")?arguments[2]:[];
               for(var k in data){
                  path.push(k);
                  if (typeof data[k] === "object"){
                      this.setObjectData(object, data[k], path);
                  } else {
                      var tmpObject = object;
                      for(var i=0,l=path.length;i<l-1;i++){
                          tmpObject = tmpObject[path[i]];
                      }
                      tmpObject[k] = data[k];
                  }
               }
            };
        };
        window.Tag = new Tag();
 
        window.Tag.extFN = window.Tag.fn.extFN = {
            /*
             * @var Object - Cache object
             */
            _cache:{},
 
            /*
             * @var Object - Pubsub provider
             */
            pubsubProvider:null,
 
            /**
             * Set the settings of a plugin
             *
             * @param settings Object - New values for settings
             *
             * @return Object - Current plugin for chainability
             */
            setConfig:function(settings) {
               window.Tag.setObjectData(this.settings, settings);
               return this;
            },
 
            /**
             * Inject another Pubsub Provider
             *
             * @param obj Object - The new Pubsub Provider
             *
             * @return Object - Current plugin for chainability
             */
            setPubsubProvider:function(obj) {
                // verify if necessary functionality is present:
                var fns = ["subscribe","unsubscribe","notify"];
 
                var validObject = true;
                $.each(fns,function(){
                    if (typeof obj[this] !== "function"){
                        validObject = false;
                        return;
                    }
                });
 
                if (validObject) {
                    this.pubsubProvider = obj;
                }
 
                return this;
            },
 
            /**
             * Get the Pubsub Provider
             *
             * @return Object - Pubsub Provider
             */
            getPubsubProvider:function() {
                // lazy loading:
                if (null === this.pubsubProvider) {
                    this.pubsubProvider = window.Tag.pubsub;
                }
 
                return this.pubsubProvider;
            },
 
            /**
             * Returns the base object
             *
             * @return Object
             */
            getParent:function() {
                return window.Tag;
            },
 
            /**
             * Automagically determines correct name of a plugin
             *
             * @return String
             */
            _toString:function() {
                // Because a loop is costly, we'll only do it once, and cache
                // the result of the loop
                if (typeof this._cache['_toString'] === 'undefined') {
                    // the name is not cached, so we need to cache it:
                    this._cache['_toString'] = '';
                    for(var k in window.Tag.fn) {
                        if (window.Tag.fn[k] === this) {
                            this._cache['_toString'] = 'Tag.' + k;
                            break;
                        }
                    }
                }
 
                // notify the user that this is an unknown plugin
                if (this._cache['_toString'] === '') {
                    alert('Could not determine the name of the plugin');
                }
 
                // return the cached name:
                return this._cache['_toString'];
            }
        };
    }
})(jQuery);

That’s the entire base class for now. As you can see, “setPubsubProvider” verifies if the new provider has all three required methods. I added this so that the plugins don’t have to be rewritten. If a new Pubsub Provider is introduced, with different names for the methods, then all you have to do is write an adapter for it, and set it via “setPubsubProvider”.

Usage

A lot of code has been written and added. Here are some examples how all this can be used. For most examples, I’ll use a fictive “Tag.autosuggest” plugin:

// inside the Tag.autosuggest plugin, we throw an event:
this.getPubsubProvider().notify(this._toString(),'thresholdReached');

(you see, no ‘Tag’ mentioned here. I like!)

Inside another plugin, we listen for the above event:

var id = this.getPubsubProvider().subscribe(this.getParent().autosuggest._toString(),'thresholdReached',function(){
    alert('Treshold has been reached');
});

(Still no mention of ‘Tag’ here. True, we have to write a lot of code, but it’s future proof)

Instead of an anonymous function, I want to execute a method of an object. We have to keep scope here:

var id = this.getPubsubProvider().subscribe(this.getParent().autosuggest._toString(),'thresholdReached',this.getParent().core.hitch(this,this.callbackFunction));

(“callbackFunction” will be executed in the correct scope)

An alternative to the above is:

var id = this.getPubsubProvider().subscribe(this.getParent().autosuggest._toString(),'thresholdReached',this.getParent().core.hitch(this,"callbackFunction"));

(Here, “callbackFunction” is specified as a string. Other than that, the exact same will happen as the previous example)

Unsubscribe from an event:

var id = this.getPubsubProvider().subscribe(this.getParent().autosuggest._toString(),'thresholdReached',this.getParent().core.hitch(this,this.callbackFunction));
 
this.getPubsubProvider().unsubscribe(id);

All above examples implied another plugin. But the code can also be used in regular Javascript, provided that Tag and Tag.pubsub are available on the page.

function doCalculation (a, b) {
    Tag.pubspub.notify('doCalculation','beforeCalculation');
    var result = a + b;
    Tag.pubspub.notify('doCalculation','afterCalculation');
    return result;
}
 
var id = Tag.pubsub.subscribe('doCalculation','afterCalculation',function(){
    alert('Calculation complete');
});
 
Tag.pubsub.unsubscribe(id);

Instead of the plugin name, I provided the function name to the “notify” and “subscribe” methods.

Conclusion

Finally, the end of a lengthy article. With the pubsub plugin, it should be easy to make your plugins event-driven, and loosely coupled. Already, a shortcoming is visible: It should be possible to transmit data from the notifier to the subscriber. In the coming days or maybe next week, I’ll refactor the code to allow that. Once that feature is added, it will be possible to write your application as a blackboard system, with all functionality independent from each other.

In these articles, I have introduced some principles from the OO world, like Dependency Injection, modular design, lazy loading, DRY, … If you want to read them again, the first article is available here, and the second article is available here. The code of this library is under constant development. I’ve made it available under the MIT license on my Codaset account on http://www.codaset.com/theanalogguy/the-analog-guy-javascript-library. Feel free to fork it, add change requests or bug reports. If you want to use the code, and you create plugins for it, please let me know. I’m curious if and how this will be used by other people.

Thank you for reading my article. Hope you enjoyed it.

Building your own Javascript library (part 2)

Tom — Tue, 01 Dec 2009 16:15:53 +0000

Goal

In this second installment of my 3-part library-building journey, I’m going to make the core plugin for the library. This plugin will contain utility methods. Stuff that can be used, either by other plugins, or just by regular Javascript code. So far, I haven’t needed many utility methods, so this chapter will be rather short. If you’re ready, read on!

Creating the Core plugin

So far, the only functionality I have needed, was dynamically loading other Javascript files on a page. jQuery is perfectly capable of doing just that. I’m just going to wrap it up in a method or two.

First, let’s start off with the base of my plugin. A self-contained, anonymous function that will be executed immediately.

(function(){
    var core = {
 
    };
 
    // Let's put this in the 'core' namespace of TAG:
    Tag.extend("core",core);
})();

In my previous blog post, there were some extra’s there: settings and an init method. I won’t be needing those at this moment, so I left them out.

There are two important things I need when dynamically loading other Javascript files. I want to be able to do something when the file is loaded. And in some cases I want to make sure that a file is loaded only once. The reason for that last feature is that when I want to create self-contained partials, I don’t want to load the same file over and over again when that partial is put on my page more than once.

That being said, the first method will accept a file URL and optionally a callback. The callback allows me to execute code after the file was loaded.

(function(){
    var core = {
        /**
         * Loads a JS library via Ajax and execute an optional callback function
         *
         * @param url String - The location of the script
         * @param callback Function - Optional callback to execute after script was loaded
         * @return Object - Core plugin for chainability
         */
        loadJS:function(url,callback){
            if (typeof callback === "undefined") {
                callback = function(){};
            }
 
            // load it via Ajax
            $.getScript(url,callback);
            return this;
        }
    };
 
    // Let's put this in the 'core' namespace of TAG:
    Tag.extend("core",core);
})();

As you can see, I just used jQuery’s getScript() method, so all restrictions apply. The return value of the method is the current object or scope. This allows you to chain multiple methods, like this:

	Tag.core.loadJS('/path/to/first.js').loadJS('/path/to/second.js').someOtherFunctionFromCore();

This keeps it all nice and tidy. You can read up on chainability in Javascript here on Javascript Ant. Chaining methods is commonly used in PHP as well. I like that principle, because it makes your code shorter and more readable.

Now that I can load 1 file, I want to be able to make sure it’s loaded only once. For that the plugin needs an extra method, and a list to put the loaded libraries in.

(function(){
    var core = {
        /**
         * @var array - List of loaded JS scripts
         */
        libraries:[],
 
        /**
         * Loads a JS library via Ajax and execute an optional callback function
         *
         * @param url String - The location of the script
         * @param callback Function - Optional callback to execute after script was loaded
         * @return Object - Core plugin for chainability
         */
        loadJS:function(url,callback){
            if (typeof callback === "undefined") {
                callback = function(){};
            }
 
            // load it via Ajax
            $.getScript(url,callback);
            return this;
        },
 
        /**
         * Loads a JS library once via Ajax, with optional callback
         *
         * @param url String - The location of the script
         * @param callback Function - Optional callback to execute after script was loaded
         * @return Object - Core plugin for chainability
         */
        loadOnce:function(url,callback){
            if (typeof callback === "undefined"){
                callback = function(){};
            }
 
            if ($.inArray(url,this.libraries) == -1) {
                // load JS:
                this.loadJS(url, callback);
 
                // append to list:
                this.libraries.push(url);
            } else {
                // just execute the callback when the library is already loaded
                callback();
            }
            return this;
        }
    };
 
    // Let's put this in the 'core' namespace of TAG:
    Tag.extend("core",core);
})();

The “loadOnce” method takes the same input as the “loadJS” method. But as a bonus, it keeps track of the files it has loaded. When some code is trying to load a file for the second time, then there is no penalty. The callback will just be executed, just as if it were the first time the file was loaded.

Usage

I’ll just give you some examples. Simplest case, you just want to load a file:

	Tag.core.loadJS('/path/to/file.js');

Load a couple of files:

	Tag.core.loadJS('/path/to/file.js');
	Tag.core.loadJS('/path/to/anotherfile.js');
 
	// OR
	Tag.core.loadJS('/path/to/file.js').loadJS('/path/to/anotherfile.js');

Load a file, and then execute some code:

	Tag.core.loadJS('/path/to/file.js',function(){
		alert('File is loaded');
	});

Load a file after another file was loaded:

	Tag.core.loadJS('/path/to/file.js',function(){
		Tag.core.loadJS('/path/to/anotherfile.js');
	});

Load a plugin, and then set the correct settings for it:

	Tag.core.loadJS('/path/to/myPlugin.js',function(){
		Tag.myPlugin.setConfig({
			url:'http://www.example.com/',
			selectors:{
				exampleLink:'.example'
			}
		});
	});

The list could go on forever. All these examples are also valid for the “loadOnce” method.

In the last part of this series, I’ll create my Pubsub plugin: an event dispatcher. For this, I will have to modify the base class a bit, as I want to make use of Dependency Injection. But that’s for tomorrow.

All code is still available on my Codaset account here: http://www.codaset.com/theanalogguy/the-analog-guy-javascript-library

Enjoy!

Building your own Javascript library (part 1)

Tom — Mon, 30 Nov 2009 18:39:56 +0000

Goal

There are two programming languages I like: PHP and Javascript. In this mini series, I will explore Javascript and jQuery, and build my own library/framework. I won’t re-invent the wheel here. I’ll just make a collection of methods and functionality I need, making use of some functionality in jQuery.

The goal of the first part of my mission is to create a small, lightweight, self-contained, easily extensible base for my framework. Recently I created my own little company, called “The Analog Guy”. I’ll just call my library “TAG”.

Creating the base

One thing I have learned from using other libraries, is that I don’t like initializing an object in Javascript. I just want to include the script on my page, and it has to work out of the box. I’ll use a self-executing anonymous function to encapsulate my class, initialize it, and add some functionality. We start with the blueprint of the self-executing anonymous function:

(function($){
    // rest goes here
})(jQuery)

This is an anonymous function that will be executed immediately. As a parameter to this anonymous function, I give the jQuery object. This makes sure that inside my anonymous function, $ refers to the jQuery object. Even if on the rest of the page, another library is used that defines $. That’s called the scope of the object.

So well, next thing I want to do, is reserve my own TAG namespace. So I’ll add a little code for that:

(function($){
    if (typeof window.Tag == "undefined"){
        var Tag = window.Tag = function(){
            // rest goes here
        }
    }
})(jQuery)

If another script uses the “Tag” namespace in the global scope, then that might indicate that the user has accidentally included the tag.js file twice on the same page. I’ve made sure that it the namespace only gets defined just once.

In my goal, I said I was going to build this library on top of jQuery. I want to make sure that $ is defined, and that it is jQuery. I don’t want to support other libraries at this moment.

(function($){
    if (typeof window.Tag == "undefined"){
        var Tag = window.Tag = function(){
            // We have a dependency on jQuery:
            if (typeof $ === "undefined" || $ !== window.jQuery){
                alert("Please load jQuery library first");
            }
        }
    }
})(jQuery)

Now that I know that jQuery is available, the next thing I want to add, is extensibility. I want to keep the base lightweight: only add the functionality that is needed. All the other functionality, that is non-essential, should be added via plugins or extensions. This makes it possible:

(function($){
    if (typeof window.Tag == "undefined"){
        var Tag = window.Tag = function(){
            // We have a dependency on jQuery:
            if (typeof $ === "undefined" || $ !== window.jQuery){
                alert("Please load jQuery library first");
            }
 
            // Object FN will contain all plugins
            this.fn = {};
 
            /**
             * Basic extend functionality. Each new plugin should extend
             * the TAG library, and become part of its namespace
             *
             * @param namespace String - Namespace of the new plugin
             * @param obj Object - The new plugin
             *
             * @return void
             */
            this.extend = function(namespace,obj){
                if (typeof this[namespace] == "undefined"){
                    if (typeof this.fn[namespace] === "undefined" && typeof this[namespace] === "undefined"){
                        // extend each namespace with core functionality
                        $.extend(obj,this.fn.extFN);
 
                        // load the new plugin in the namespaces:
                        this.fn[namespace] = obj;
                        this[namespace] = this.fn[namespace];
 
                        // initialize the new library if necessary
                        if (typeof this[namespace].init === "function"){
                            this[namespace].init();
                        }
                    } else {
                        alert("The namespace '" + namespace + "' is already taken...");
                    }
                }
            };
        }
    }
})(jQuery)

The extend method has two arguments: the name of the namespace the plugin wants to use, and then the plugin itself. First there is a check if that namespace is still available. If it is, the first thing I do, is add some basic functionality to the plugin, that will make life easier for the developer of that plugin. Don’t worry, we’ll see immediately where I add that core functionality. A next step is to inject the plugin into the base class. For this, I use the “this.fn” object, because that makes it easier to detect which plugins are loaded. As a “bonus”, I also inject that same plugin in the base namespace. That makes it more convenient to use the plugin. “Tag.fn.myPlugin” can be referred to as “Tag.myPlugin”. Lastly, if that plugin needs some automagical setup, it can define the “init” method, which will get triggered when loading the plugin.

This provides basic extensibility for my framework. The next method I need, is a utility method. I cannot place it on a plugin, because it is something basic: a method that recursively sets a value inside an object

(function($){
    if (typeof window.Tag == "undefined"){
        var Tag = window.Tag = function(){
            // We have a dependency on jQuery:
            if (typeof $ === "undefined" || $ !== window.jQuery){
                alert("Please load jQuery library first");
            }
 
            // Object FN will contain all plugins
            this.fn = {};
 
            /**
             * Basic extend functionality. Each new plugin should extend
             * the TAG library, and become part of its namespace
             *
             * @param namespace String - Namespace of the new plugin
             * @param obj Object - The new plugin
             *
             * @return void
             */
            this.extend = function(namespace,obj){
                if (typeof this[namespace] == "undefined"){
                    if (typeof this.fn[namespace] === "undefined" && typeof this[namespace] === "undefined"){
                        // extend each namespace with core functionality
                        $.extend(obj,this.fn.extFN);
 
                        // load the new plugin in the namespaces:
                        this.fn[namespace] = obj;
                        this[namespace] = this.fn[namespace];
 
                        // initialize the new library if necessary
                        if (typeof this[namespace].init === "function"){
                            this[namespace].init();
                        }
                    } else {
                        alert("The namespace '" + namespace + "' is already taken...");
                    }
                }
            };
 
            /**
             * Recursively set values in an object
             *
             * Method allows to set individual settings, without overwriting
             * existing other values in the settings.
             *
             * @param object Object - The object to modify
             * @param data Object - New values for settings
             *
             * @return Object - Current plugin for chainability
             */
            this.setObjectData = function(object, data) {
               var path = (typeof arguments[2] !== "undefined")?arguments[2]:[];
               for(var k in data){
                  path.push(k);
                  if (typeof data[k] === "object"){
                      this.setObjectData(object, data[k], path);
                  } else {
                      var tmpObject = object;
                      for(var i=0,l=path.length;i<l-1;i++){
                          tmpObject = tmpObject[path[i]];
                      }
                      tmpObject[k] = data[k];
                  }
               }
            };
        }
    }
})(jQuery)

I know jQuery.extend() exists. I just don’t think it can do what I want: set some properties of an object, without touching other existing properties. The method “setObjectData” I just created will do just that. It recursively loops through a set of values, and sets these values on the given object. This method will be used later, for setting values in a plugin configuration.

For now, I’m happy with that functionality. I don’t have an immediate use for other functionality. So we can initialize our class now. Since this takes only 1 line of code, I’ll immediately add some more functionality.

There are certain methods, I want to be available in every plugin, without the plugin having to know the name of my base class. I think it’s a basic need of the plugins, to be as agnostic as possible about the rest of the world. The fewer the dependencies, the better. If I ever decide to rename my company, and I rename my base library. Then the plugin should still work with little or no effort. These methods are “setConfig”, to set values in a plugin config, and “toString”, to automagically determine the name of the plugin.

(function($){
    if (typeof window.Tag == "undefined"){
        var Tag = window.Tag = function(){
            // We have a dependency on jQuery:
            if (typeof $ === "undefined" || $ !== window.jQuery){
                alert("Please load jQuery library first");
            }
 
            // Object FN will contain all plugins
            this.fn = {};
 
            /**
             * Basic extend functionality. Each new plugin should extend
             * the TAG library, and become part of its namespace
             *
             * @param namespace String - Namespace of the new plugin
             * @param obj Object - The new plugin
             *
             * @return void
             */
            this.extend = function(namespace,obj){
                if (typeof this[namespace] == "undefined"){
                    if (typeof this.fn[namespace] === "undefined" && typeof this[namespace] === "undefined"){
                        // extend each namespace with core functionality
                        $.extend(obj,this.fn.extFN);
 
                        // load the new plugin in the namespaces:
                        this.fn[namespace] = obj;
                        this[namespace] = this.fn[namespace];
 
                        // initialize the new library if necessary
                        if (typeof this[namespace].init === "function"){
                            this[namespace].init();
                        }
                    } else {
                        alert("The namespace '" + namespace + "' is already taken...");
                    }
                }
            };
 
            /**
             * Recursively set values in an object
             *
             * Method allows to set individual settings, without overwriting
             * existing other values in the settings.
             *
             * @param object Object - The object to modify
             * @param data Object - New values for settings
             *
             * @return Object - Current plugin for chainability
             */
            this.setObjectData = function(object, data) {
               var path = (typeof arguments[2] !== "undefined")?arguments[2]:[];
               for(var k in data){
                  path.push(k);
                  if (typeof data[k] === "object"){
                      this.setObjectData(object, data[k], path);
                  } else {
                      var tmpObject = object;
                      for(var i=0,l=path.length;i<l-1;i++){
                          tmpObject = tmpObject[path[i]];
                      }
                      tmpObject[k] = data[k];
                  }
               }
            };
        };
        window.Tag = new Tag();
 
        window.Tag.extFN = window.Tag.fn.extFN = {
            /**
             * Set the settings of a plugin
             *
             * @param settings Object - New values for settings
             *
             * @return Object - Current plugin for chainability
             */
            setConfig:function(settings) {
               window.Tag.setObjectData(this.settings, settings);
               return this;
            },
 
            /**
             * Automagically determines correct name of a plugin
             *
             * @return String
             */
            toString:function() {
                for(var k in window.Tag.fn) {
                    if (window.Tag.fn[k] === this) {
                        return 'Tag.' + k;
                        break;
                    }
                }
                alert('Could not determine the name of the plugin');
                return '';
            }
        };
    }
})(jQuery);

That’s it for the moment. I’ll certainly need more functionality inside the base class, but I will build it was I need it.

Usage

Well, it’s a basic class really, there is no real usage for now. The strength will come from the plugins. To include the library in your files, simply include script tags which point to the correct JS file.

Writing your own plugins

Since I’m emphasizing plugins, I’ll give you the basic structure of how a plugin should be built. In future parts, I’ll build at least two plugins that will further extend the functionality: a “core” plugin, and a “pubsub” plugin. Here’s the template:

(function(){
    var myPlugin = {
        /**
         * @var object settings - The configuration of this library
         */
        settings:{},

        /**
         * Will be called as soon as this library is loaded
         * into the main Tag library
         *
         * @return void
         */
        init:function(){},

        // other methods go below
    };
    Tag.extend("myPlugin",myPlugin);
})();

That’s all there is to it. Just an Object Literal notation of an object, again inside a self-executing anonymous function. Include your JS file in your HTML, after you included the Tag library, and your plugin will be available as “Tag.myPlugin”.

In the next part of this mini series, I’ll create the “core” plugin. This plugin will create functionality that is quite basic, but not essential to the library. Usually the methods will be utility methods which can be used by other plugins or regular Javascript code.

In the last part of the series, I’ll introduce my “pubsub” plugin. It’s a plugin that serves as a dispatcher for events. With it, it is possible to send out event notifications. Other parts of your code will be able to (un-)subscribe to events, and will get triggered when the event is fired.

If you have any remarks, please let me know. I’m open to suggestions and improvements. My code is available at http://www.codaset.com/theanalogguy/the-analog-guy-javascript-library.