Merge pull request #4371 from plotly/plotlyEvents

bpostlethwaite · bpostlethwaite · commit 6bb7d3783ecd · 2015-10-26T15:25:08.000-04:00
Plotly events
diff --git a/shelly/plotlyjs/static/plotlyjs/src/annotations.js b/shelly/plotlyjs/static/plotlyjs/src/annotations.js
@@ -603,7 +603,7 @@ annotations.draw = function(gd, index, opt, value) {
         .style('opacity', options.opacity)
         .on('click', function() {
             gd._dragging = false;
-            $(gd).trigger('plotly_clickannotation', {
+            gd.emit('plotly_clickannotation', {
                 index: index,
                 annotation: optionsIn,
                 fullAnnotation: options
diff --git a/shelly/plotlyjs/static/plotlyjs/src/events.js b/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 jQueryHandlerValue;
+
+        var handlers = ev._events[event];
+        if (!handlers) return jQueryHandlerValue;
+
+        /*
+         * 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;
diff --git a/shelly/plotlyjs/static/plotlyjs/src/graph_interact.js b/shelly/plotlyjs/static/plotlyjs/src/graph_interact.js
@@ -5,7 +5,8 @@
 var Plotly = require('./plotly'),
     d3 = require('d3'),
     tinycolor = require('tinycolor2'),
-    isNumeric = require('./isnumeric');
+    isNumeric = require('./isnumeric'),
+    Events = require('./events');
 
 var fx = module.exports = {};
 
@@ -380,7 +381,7 @@ function hover(gd, evt, subplot){
             // fire the beforehover event and quit if it returns false
             // note that we're only calling this on real mouse events, so
             // manual calls to fx.hover will always run.
-            if($(gd).triggerHandler('plotly_beforehover',evt)===false) {
+            if(Events.triggerHandler(gd, 'plotly_beforehover', evt)===false) {
                 return;
             }
 
@@ -531,7 +532,7 @@ function hover(gd, evt, subplot){
 
     alignHoverText(hoverLabels, rotateLabels);
 
-    // lastly, trigger custom hover/unhover events
+    // lastly, emit custom hover/unhover events
     var oldhoverdata = gd._hoverdata,
         newhoverdata = [];
 
@@ -556,13 +557,13 @@ function hover(gd, evt, subplot){
 
     if(!hoverChanged(gd, evt, oldhoverdata)) return;
 
-    // trigger the custom hover handler. Bind this like:
+    // emit the custom hover handler. Bind this like:
     // $(gd).on('hover.plotly',
     //    function(event,extras){ do something with extras.data });
     if(oldhoverdata) {
-        $(gd).trigger('plotly_unhover', {points: oldhoverdata});
+        gd.emit('plotly_unhover', {points: oldhoverdata});
     }
-    $(gd).trigger('plotly_hover', {
+    gd.emit('plotly_hover', {
         points: gd._hoverdata,
         xaxes: xaArray,
         yaxes: yaArray,
@@ -1231,7 +1232,7 @@ function alignHoverText(hoverLabels, rotateLabels) {
 }
 
 function hoverChanged(gd, evt, oldhoverdata) {
-    // don't trigger any events if nothing changed or
+    // don't emit any events if nothing changed or
     // if fx.hover was called manually
     if(!evt.target) return false;
     if(!oldhoverdata || oldhoverdata.length!==gd._hoverdata.length) return true;
@@ -1247,25 +1248,25 @@ function hoverChanged(gd, evt, oldhoverdata) {
     return false;
 }
 
-// remove hover effects on mouse out, and trigger unhover event
+// remove hover effects on mouse out, and emit unhover event
 function unhover(gd, evt){
     var fullLayout = gd._fullLayout;
     if(!evt) evt = {};
     if(evt.target &&
-            $(gd).triggerHandler('plotly_beforehover',evt)===false) {
+       Events.triggerHandler(gd, 'plotly_beforehover', evt) === false) {
         return;
     }
     fullLayout._hoverlayer.selectAll('g').remove();
     if(evt.target && gd._hoverdata) {
-        $(gd).trigger('plotly_unhover', {points: gd._hoverdata});
+        gd.emit('plotly_unhover', {points: gd._hoverdata});
     }
     gd._hoverdata = undefined;
 }
 
 // on click
 fx.click = function(gd,evt){
     if(gd._hoverdata && evt && evt.target) {
-        $(gd).trigger('plotly_click', {points: gd._hoverdata});
+        gd.emit('plotly_click', {points: gd._hoverdata});
         // why do we get a double event without this???
         evt.stopImmediatePropagation();
     }
diff --git a/shelly/plotlyjs/static/plotlyjs/src/graph_obj.js b/shelly/plotlyjs/static/plotlyjs/src/graph_obj.js
@@ -8,7 +8,8 @@
 var Plotly = require('./plotly'),
     d3 = require('d3'),
     m4FromQuat = require('gl-mat4/fromQuat'),
-    isNumeric = require('./isnumeric');
+    isNumeric = require('./isnumeric'),
+    Events = require('./events');
 
 var plots = module.exports = {};
 // Most of the generic plotting functions get put into Plotly.Plots,
@@ -387,7 +388,7 @@ function positionPlayWithData(gd, container){
 
     if(gd._context.sendData) {
         link.on('click',function(){
-            $(gd).trigger('plotly_beforeexport');
+            gd.emit('plotly_beforeexport');
 
             var baseUrl = (window.PLOTLYENV && window.PLOTLYENV.BASE_URL) || 'https://plot.ly';
 
@@ -402,7 +403,7 @@ function positionPlayWithData(gd, container){
             hiddenform.find('form').submit();
             hiddenform.remove();
 
-            $(gd).trigger('plotly_afterexport');
+            gd.emit('plotly_afterexport');
             return false;
         });
     }
@@ -431,7 +432,12 @@ Plotly.plot = function(gd, data, layout, config) {
 
     gd = getGraphDiv(gd);
 
-    var okToPlot = $(gd).triggerHandler('plotly_beforeplot', [data, layout, config]);
+    /*
+     * Events.init is idempotent and bails early if gd has already been init'd
+     */
+    Events.init(gd);
+
+    var okToPlot = Events.triggerHandler(gd, 'plotly_beforeplot', [data, layout, config]);
     if(okToPlot===false) return;
 
     // if there's no data or layout, and this isn't yet a plotly plot
@@ -727,7 +733,7 @@ Plotly.plot = function(gd, data, layout, config) {
         // so mark it as done and let other procedures call a replot
         gd._replotting = false;
         Plotly.Lib.markTime('done plot');
-        $(gd).trigger('plotly_afterplot');
+        gd.emit('plotly_afterplot');
     }
 
     var donePlotting = Plotly.Lib.syncOrAsync([
@@ -1255,7 +1261,7 @@ Plotly.redraw = function(gd) {
     }
     gd.calcdata = undefined;
     return Plotly.plot(gd).then(function () {
-        $(gd).trigger('plotly_redraw');
+        gd.emit('plotly_redraw');
     });
 };
 
@@ -3049,7 +3055,7 @@ Plotly.restyle = function restyle(gd, astr, val, traces) {
     if(!plotDone || !plotDone.then) plotDone = Promise.resolve();
 
     return plotDone.then(function(){
-        $(gd).trigger('plotly_restyle',
+        gd.emit('plotly_restyle',
             Plotly.Lib.extendDeep([], [redoit, traces]));
     });
 };
@@ -3410,7 +3416,7 @@ Plotly.relayout = function relayout(gd, astr, val) {
     if(!plotDone || !plotDone.then) plotDone = Promise.resolve();
 
     return plotDone.then(function(){
-        $(gd).trigger('plotly_relayout',
+        gd.emit('plotly_relayout',
             Plotly.Lib.extendDeep({}, redoit));
     });
 };
@@ -3444,7 +3450,7 @@ function plotAutoSize(gd, aobj) {
 
     var newHeight, newWidth;
 
-    $(gd).trigger('plotly_autosize');
+    gd.emit('plotly_autosize');
 
     // embedded in an iframe - just take the full iframe size
     // if we get to this point, with no aspect ratio restrictions
@@ -3629,7 +3635,7 @@ function makePlotFramework(gd) {
     fullLayout._infolayer = fullLayout._toppaper.append('g').classed('infolayer', true);
     fullLayout._hoverlayer = fullLayout._toppaper.append('g').classed('hoverlayer', true);
 
-    $(gd).trigger('plotly_framework');
+    gd.emit('plotly_framework');
 
     // position and style the containers, make main title
     var frameWorkDone = Plotly.Lib.syncOrAsync([
diff --git a/shelly/plotlyjs/static/plotlyjs/tests/events_test.js b/shelly/plotlyjs/static/plotlyjs/tests/events_test.js
