issue/1814: turn Adapt wait into hard API

src/core/js/adapt.js

@@ -1,6 +1,7 @@
 define([
-    'core/js/models/lockingModel'
-], function(lockingModel) {
+    'core/js/models/lockingModel',
+    'core/js/wait'
+], function(lockingModel, Wait) {
 
     var AdaptModel = Backbone.Model.extend({
 
@@ -15,8 +16,7 @@ define([
         },
 
         initialize: function () {
-            this.listenTo(this, 'plugin:beginWait', this.onPluginBeginWait);
-            this.listenTo(this, 'plugin:endWait', this.onPluginEndWait);
+            this.setupWait();
         },
 
         //call when entering an asynchronous completion check
@@ -48,24 +48,58 @@ define([
 
         },
 
-        isWaitingForPlugins:function() {
-            return this.get('_pluginWaitCount') > 0;
-        },
+        setupWait: function() {
+
+            this.wait = new Wait();
+
+            // Setup legcay events and handlers
+            var beginWait = function () {
+                Adapt.log.warn("DEPRECATED - Use Adapt.wait.begin() as Adapt.trigger('plugin:beginWait') may be removed in the future");
+                this.wait.begin();
+            }.bind(this);
+
+            var endWait = function() {
+                Adapt.log.warn("DEPRECATED - Use Adapt.wait.end() as Adapt.trigger('plugin:endWait') may be removed in the future");
+                this.wait.end();
+            }.bind(this);
+
+            var ready = function() {
+
+                if (this.wait.isWaiting()) {
+                    return;
+                }
+
+                var isEventListening = (this._events['plugins:ready']);
+                if (!isEventListening) {
+                    return;
+                }
+
+                Adapt.log.warn("DEPRECATED - Use Adapt.wait.queue(callback) as Adapt.on('plugins:ready', callback) may be removed in the future");
+                this.trigger('plugins:ready');
+
+            }.bind(this);
+
+            this.listenTo(this.wait, "ready", ready);
+            this.listenTo(this, {
+                'plugin:beginWait': beginWait,
+                'plugin:endWait': endWait
+            });
 
-        checkPluginsReady:function() {
-            if (this.isWaitingForPlugins()) return;
-            this.trigger('plugins:ready');
         },
 
-        onPluginBeginWait:function() {
-            this.set('_pluginWaitCount', this.get('_pluginWaitCount') + 1);
-            this.checkPluginsReady();
+        isWaitingForPlugins:function() {
+            Adapt.log.warn("DEPRECATED - Use Adapt.wait.isWaiting() as Adapt.isWaitingForPlugins() may be removed in the future");
+            return this.wait.isWaiting();
         },
 
-        onPluginEndWait:function() {
-            this.set('_pluginWaitCount', this.get('_pluginWaitCount') - 1);
-            this.checkPluginsReady();
+        checkPluginsReady:function() {
+            Adapt.log.warn("DEPRECATED - Use Adapt.wait.isWaiting() as Adapt.checkPluginsReady() may be removed in the future");
+            if (this.isWaitingForPlugins()) {
+                return;
+            }
+            this.trigger('plugins:ready');
         }
+
     });
 
     var Adapt = new AdaptModel();

src/core/js/app.js

@@ -80,13 +80,10 @@ require([
 
             Adapt.setupMapping();
 
-            if (!Adapt.isWaitingForPlugins()) {
+            Adapt.wait.queue(function() {
                 triggerDataReady(newLanguage);
-            } else {
-                Adapt.once('plugins:ready', function() {
-                    triggerDataReady(newLanguage);
-                });
-            }
+            });
+
         }
     };
 
@@ -115,11 +112,8 @@ require([
             Adapt.log.error('Error during app:dataReady trigger', e);
         }
 
-        if (!Adapt.isWaitingForPlugins()) {
-            triggerInitialize();
-        } else {
-            Adapt.once('plugins:ready', triggerInitialize);
-        }
+        Adapt.wait.queue(triggerInitialize);
+
     }
 
     function triggerInitialize() {

src/core/js/router.js

@@ -196,8 +196,8 @@ define([
         removeViews: function(onComplete) {
             Adapt.remove();
 
-            if (!Adapt.isWaitingForPlugins()) onComplete();
-            else Adapt.once('plugins:ready', onComplete);
+            Adapt.wait.queue(onComplete);
+
         },
 
         showLoading: function() {
@@ -338,8 +338,8 @@ define([
             // Trigger event when location changes
             Adapt.trigger('router:location', Adapt.location);
 
-            if (!Adapt.isWaitingForPlugins()) onComplete();
-            else Adapt.once('plugins:ready', onComplete);
+            Adapt.wait.queue(onComplete);
+
         },
 
         setDocumentTitle: function() {

src/core/js/views/adaptView.js

@@ -126,17 +126,19 @@ define([
         preRemove: function() {},
 
         remove: function() {
-            Adapt.trigger('plugin:beginWait');
+
             this.preRemove();
             this._isRemoved = true;
 
-            _.defer(_.bind(function() {
+            Adapt.wait.for(function(end) {
+
                 this.$el.off('onscreen.adaptView');
                 this.model.setOnChildren('_isReady', false);
                 this.model.set('_isReady', false);
                 Backbone.View.prototype.remove.call(this);
-                Adapt.trigger('plugin:endWait');
-            }, this));
+
+                end();
+            }.bind(this));
 
             return this;
         },

src/core/js/wait.js

@@ -0,0 +1,112 @@
+define(function() {
+
+     var Wait = Backbone.Controller.extend({
+
+        initialize: function() {
+            _.bindAll(this, "begin", "end");
+        },
+
+        _waitCount: 0,
+        _callbackHandle: null,
+
+        /**
+         * Returns true if there are items in the waiting count.
+         * 
+         * @return {Boolean}
+         */
+        isWaiting: function() {
+            return (this._waitCount !== 0);
+        },
+
+        /**
+         * Add one item to the waiting count.
+         * 
+         * @return {Object}
+         */
+        begin: function() {
+
+            if (!this.isWaiting()) {
+                this.trigger("wait");
+            }
+
+            this._waitCount++;
+
+            if (this._callbackHandle) {
+                clearTimeout(this._callbackHandle);
+                this._callbackHandle = null;
+            }
+
+            return this;
+
+        },
+
+        /**
+         * Remove an item from the waiting count and trigger ready asynchronously if no more items are waiting.
+         * 
+         * @return {Object}
+         */
+        end: function() {
+
+            if (!this.isWaiting()) {
+                return this;
+            }
+
+            this._waitCount--;
+
+            if (this.isWaiting()) {
+                return this;
+            }
+
+            if (this._callbackHandle) {
+                return this;
+            }
+
+            this._callbackHandle = setTimeout(function() {
+
+                this._callbackHandle = null;
+                this.trigger("ready");
+
+            }.bind(this), 0);
+
+            return this;
+
+        },
+
+        /**
+         * Queue this function until all open waits have been ended.
+         * 
+         * @param  {Function} callback
+         * @return {Object}
+         */
+        queue: function(callback) {
+
+            this.begin();
+            this.once("ready", callback);
+            this.end();
+
+            return this;
+
+        },
+
+        /**
+         * Wait for this asynchonous function to execute before triggering ready event.
+         * 
+         * @param  {Function} callback   [ Function to execute whilst holding queued callback. Once complete run first argiument, done(). ]
+         * @return {Object}
+         */
+        for: function(callback) {
+
+            this.begin();
+            _.defer(function() {
+                callback(this.end);
+            }.bind(this));
+
+            return this;
+
+        }
+
+    });
+
+    return Wait;
+
+});