add 'plotly_legendclick' and 'plotly_doubleclick' events

... and use their return val to determine whether or not
    the default handler is called after them. This allows users
    to disable legend trace toggling and/or augment it!

Author: etpinard

src/components/legend/draw.js

@@ -13,6 +13,7 @@ var d3 = require('d3');
 var Lib = require('../../lib');
 var Plots = require('../../plots/plots');
 var Registry = require('../../registry');
+var Events = require('../../lib/events');
 var dragElement = require('../dragelement');
 var Drawing = require('../drawing');
 var Color = require('../color');
@@ -336,22 +337,46 @@ module.exports = function draw(gd) {
                             e.clientY >= bbox.top && e.clientY <= bbox.bottom);
                     });
                 if(clickedTrace.size() > 0) {
-                    if(numClicks === 1) {
-                        legend._clickTimeout = setTimeout(function() {
-                            handleClick(clickedTrace, gd, numClicks);
-                        }, DBLCLICKDELAY);
-                    } else if(numClicks === 2) {
-                        if(legend._clickTimeout) {
-                            clearTimeout(legend._clickTimeout);
-                        }
-                        handleClick(clickedTrace, gd, numClicks);
-                    }
+                    clickOrDoubleClick(gd, legend, clickedTrace, numClicks, e);
                 }
             }
         });
     }
 };
 
+function clickOrDoubleClick(gd, legend, clickedTrace, numClicks, evt) {
+    var datum = clickedTrace.data()[0][0];
+
+    var evtData = {
+        event: evt,
+        node: clickedTrace.node(),
+        itemNumber: datum.i,
+        curveNumber: datum.trace.index,
+        data: gd.data,
+        layout: gd.layout,
+        frames: gd._transitionData._frames,
+        config: gd._context,
+        fullData: gd._fullData,
+        fullLayout: gd._fullLayout
+    };
+
+    var returnVal;
+
+    if(numClicks === 1) {
+        legend._clickTimeout = setTimeout(function() {
+            returnVal = Events.triggerHandler(gd, 'plotly_legendclick', evtData);
+            if(returnVal !== false) handleClick(clickedTrace, gd, numClicks);
+        }, DBLCLICKDELAY);
+    }
+    else if(numClicks === 2) {
+        if(legend._clickTimeout) clearTimeout(legend._clickTimeout);
+        gd._legendMouseDownTime = 0;
+
+        returnVal = Events.triggerHandler(gd, 'plotly_legenddoubleclick', evtData);
+        if(returnVal !== false) handleClick(clickedTrace, gd, numClicks);
+    }
+}
+
 function drawTexts(g, gd) {
     var legendItem = g.data()[0][0],
         fullLayout = gd._fullLayout,
@@ -441,15 +466,7 @@ function setupTraceToggle(g, gd) {
             numClicks = Math.max(numClicks - 1, 1);
         }
 
-        if(numClicks === 1) {
-            legend._clickTimeout = setTimeout(function() { handleClick(g, gd, numClicks); }, DBLCLICKDELAY);
-        } else if(numClicks === 2) {
-            if(legend._clickTimeout) {
-                clearTimeout(legend._clickTimeout);
-            }
-            gd._legendMouseDownTime = 0;
-            handleClick(g, gd, numClicks);
-        }
+        clickOrDoubleClick(gd, legend, g, numClicks, d3.event);
     });
 }
 

test/jasmine/tests/legend_test.js

@@ -1001,9 +1001,13 @@ describe('legend interaction', function() {
             };
         }
 
+        function extractVisibilities(data) {
+            return data.map(function(trace) { return trace.visible; });
+        }
+
         function assertVisible(expectation) {
             return function() {
-                var actual = gd._fullData.map(function(trace) { return trace.visible; });
+                var actual = extractVisibilities(gd._fullData);
                 expect(actual).toEqual(expectation);
             };
         }
@@ -1166,5 +1170,101 @@ describe('legend interaction', function() {
                     .catch(failTest).then(done);
             });
         });
+
+        describe('custom legend click/doubleclick handlers', function() {
+            var fig, to;
+
+            beforeEach(function() {
+                fig = Lib.extendDeep({}, require('@mocks/0.json'));
+            });
+
+            afterEach(function() {
+                clearTimeout(to);
+            });
+
+            function setupFail() {
+                to = setTimeout(function() {
+                    fail('did not trigger plotly_legendclick');
+                }, 2 * DBLCLICKDELAY);
+            }
+
+            it('should call custom click handler before default handler', function(done) {
+                Plotly.newPlot(gd, fig).then(function() {
+                    var gotCalled = false;
+
+                    gd.on('plotly_legendclick', function(d) {
+                        gotCalled = true;
+                        expect(extractVisibilities(d.fullData)).toEqual([true, true, true]);
+                        expect(extractVisibilities(gd._fullData)).toEqual([true, true, true]);
+                    });
+                    gd.on('plotly_restyle', function() {
+                        expect(extractVisibilities(gd._fullData)).toEqual([true, 'legendonly', true]);
+                        if(gotCalled) done();
+                    });
+                    setupFail();
+                })
+                .then(click(1, 1))
+                .catch(failTest);
+            });
+
+            it('should call custom doubleclick handler before default handler', function(done) {
+                Plotly.newPlot(gd, fig).then(function() {
+                    var gotCalled = false;
+
+                    gd.on('plotly_legenddoubleclick', function(d) {
+                        gotCalled = true;
+                        expect(extractVisibilities(d.fullData)).toEqual([true, true, true]);
+                        expect(extractVisibilities(gd._fullData)).toEqual([true, true, true]);
+                    });
+                    gd.on('plotly_restyle', function() {
+                        expect(extractVisibilities(gd._fullData)).toEqual(['legendonly', true, 'legendonly']);
+                        if(gotCalled) done();
+                    });
+                    setupFail();
+                })
+                .then(click(1, 2))
+                .catch(failTest);
+            });
+
+            it('should not call default click handler if custom handler return *false*', function(done) {
+                Plotly.newPlot(gd, fig).then(function() {
+                    gd.on('plotly_legendclick', function(d) {
+                        Plotly.relayout(gd, 'title', 'just clicked on trace #' + d.curveNumber);
+                        return false;
+                    });
+                    gd.on('plotly_relayout', function(d) {
+                        expect(typeof d).toBe('object');
+                        expect(d.title).toBe('just clicked on trace #2');
+                        done();
+                    });
+                    gd.on('plotly_restyle', function() {
+                        fail('should not have triggered plotly_restyle');
+                    });
+                    setupFail();
+                })
+                .then(click(2, 1))
+                .catch(failTest);
+            });
+
+            it('should not call default doubleclick handle if custom handler return *false*', function(done) {
+                Plotly.newPlot(gd, fig).then(function() {
+                    gd.on('plotly_legenddoubleclick', function(d) {
+                        Plotly.relayout(gd, 'title', 'just double clicked on trace #' + d.curveNumber);
+                        return false;
+                    });
+                    gd.on('plotly_relayout', function(d) {
+                        expect(typeof d).toBe('object');
+                        expect(d.title).toBe('just double clicked on trace #0');
+                        done();
+                    });
+                    gd.on('plotly_restyle', function() {
+                        fail('should not have triggered plotly_restyle');
+                    });
+                    setupFail();
+                })
+                .then(click(0, 2))
+                .catch(failTest);
+            });
+        });
     });
 });