Event module and tests

Author: bpostlethwaite

shelly/plotlyjs/static/plotlyjs/src/events.js

@@ -0,0 +1,109 @@
+'use strict';
+
+var EventEmitter = require('events').EventEmitter;
+
+var Events = {
+
+    init: function(plotObj) {
+
+        /*
+         * If we have already instantiated an emitter for this plot
+         * return early.
+         */
+        if (plotObj._ev instanceof  EventEmitter) return plotObj;
+
+        var ev = new EventEmitter();
+
+        /*
+         * Assign to plot._ev while we still live in a land
+         * where plot is a DOM element with stuff attached to it.
+         * In the future we can make plot the event emitter itself.
+         */
+        plotObj._ev = ev;
+
+        /*
+         * Assign bound methods from the ev to the plot object. These methods
+         * will reference the 'this' of plot._ev even though they are methods
+         * of plot. This will keep the event machinery away from the plot object
+         * which currently is often a DOM element but presents an API that will
+         * continue to function when plot becomes an emitter. Not all EventEmitter
+         * methods have been bound to `plot` as some do not currently add value to
+         * the Plotly event API.
+         */
+        plotObj.on = ev.on.bind(ev);
+        plotObj.once = ev.once.bind(ev);
+        plotObj.removeListener = ev.removeListener.bind(ev);
+        plotObj.removeAllListeners = ev.removeAllListeners.bind(ev);
+
+        /*
+         * We must wrap emit to continue to support JQuery events. The idea
+         * is to check to see if the user is using JQuery events, if they are
+         * we emit JQuery events to trigger user handlers as well as the EventEmitter
+         * events.
+         */
+        plotObj.emit = function(event, data) {
+            if (typeof $ !== 'undefined') {
+                $(plotObj).trigger(event, data);
+            }
+
+            ev.emit(event, data);
+        };
+
+        return plotObj;
+    },
+
+    /*
+     * This function behaves like jQueries triggerHandler. It calls
+     * all handlers for a particular event and returns the return value
+     * of the LAST handler. This function also triggers jQuery's
+     * triggerHandler for backwards compatibility.
+     */
+    triggerHandler: function(plotObj, event, data) {
+        var jQueryHandlerValue;
+        var nodeEventHandlerValue;
+        /*
+         * If Jquery exists run all its handlers for this event and
+         * collect the return value of the LAST handler function
+         */
+        if (typeof $ !== 'undefined') {
+            jQueryHandlerValue = $(plotObj).triggerHandler(event, data);
+        }
+
+        /*
+         * Now run all the node style event handlers
+         */
+        var ev = plotObj._ev;
+        if (!ev) return;
+
+        var handlers = ev._events[event];
+        if (!handlers) return;
+
+        /*
+         * handlers can be function or an array of functions
+         */
+        if (typeof handlers === 'function') handlers = [handlers];
+        var lastHandler = handlers.pop();
+
+        /*
+         * Call all the handlers except the last one.
+         */
+        for (var i = 0; i < handlers.length; i++) {
+            handlers[i](data);
+        }
+
+        /*
+         * Now call the final handler and collect its value
+         */
+        nodeEventHandlerValue = lastHandler(data);
+
+        /*
+         * Return either the jquery handler value if it exists or the
+         * nodeEventHandler value. Jquery event value superceeds nodejs
+         * events for backwards compatability reasons.
+         */
+        return jQueryHandlerValue !== undefined ? jQueryHandlerValue :
+            nodeEventHandlerValue;
+    }
+};
+
+module.exports = Events;

shelly/plotlyjs/static/plotlyjs/tests/events_test.js

@@ -0,0 +1,133 @@
+/*
+ * Note this test requires JQuery in the global scope.
+ * we should keep it that way to keep testing our backward
+ * compatibility with JQuery events.
+ */
+
+
+var Events = require('../src/events');
+
+describe('Events', function () {
+    'use strict';
+
+    var plotObj;
+    var plotDiv;
+
+    beforeEach(function() {
+        plotObj = {};
+        plotDiv = document.createElement('div');
+    });
+
+    describe('init', function() {
+
+        it('instantiates an emitter on incoming plot object', function() {
+            expect(plotObj._ev).not.toBeDefined();
+            expect(Events.init(plotObj)._ev).toBeDefined();
+        });
+
+        it('maps function onto incoming plot object', function() {
+            Events.init(plotObj);
+
+            expect(typeof plotObj.on).toBe('function');
+            expect(typeof plotObj.once).toBe('function');
+            expect(typeof plotObj.removeListener).toBe('function');
+            expect(typeof plotObj.removeAllListeners).toBe('function');
+        });
+
+        it('is idempotent', function() {
+            Events.init(plotObj);
+            plotObj.emit = function () {
+                return 'initial';
+            };
+
+            Events.init(plotObj);
+            expect(plotObj.emit()).toBe('initial');
+        });
+
+        it('triggers node style events', function(done) {
+            Events.init(plotObj);
+
+            plotObj.on('ping', function(data) {
+                expect(data).toBe('pong');
+                done();
+            });
+
+            setTimeout(function() {
+                plotObj.emit('ping', 'pong');
+            });
+        });
+
+        it('triggers jquery events', function(done) {
+            Events.init(plotDiv);
+
+
+            $(plotDiv).bind('ping', function(event, data) {
+                expect(data).toBe('pong');
+                done();
+            });
+
+            setTimeout(function() {
+                $(plotDiv).trigger('ping', 'pong');
+            });
+        });
+    });
+
+    describe('triggerHandler', function() {
+
+        it('triggers node handlers and returns last value', function() {
+            var eventBaton = 0;
+
+            Events.init(plotDiv);
+
+            plotDiv.on('ping', function() {
+                eventBaton++;
+                return 'ping';
+            });
+
+            plotDiv.on('ping', function() {
+                eventBaton++;
+                return 'ping';
+            });
+
+            plotDiv.on('ping', function() {
+                eventBaton++;
+                return 'pong';
+            });
+
+            var result = Events.triggerHandler(plotDiv, 'ping');
+
+            expect(eventBaton).toBe(3);
+            expect(result).toBe('pong');
+        });
+
+
+        it('triggers jQuery + nodejs handlers and returns last jQuery value', function() {
+            var eventBaton = 0;
+
+            Events.init(plotDiv);
+
+            $(plotDiv).bind('ping', function() {
+                eventBaton++;
+                return 'ping';
+            });
+
+            plotDiv.on('ping', function() {
+                eventBaton++;
+                return 'ping';
+            });
+
+            $(plotDiv).bind('ping', function() {
+                eventBaton++;
+                return 'pong';
+            });
+
+            var result = Events.triggerHandler(plotDiv, 'ping');
+
+            expect(eventBaton).toBe(3);
+            expect(result).toBe('pong');
+        });
+
+
+    });
+
+});