extras/synchronizer.js

   1 /**
   2  * Synchronize zooming and/or selections between a set of dygraphs.
   3  *
   4  * Usage:
   5  *
   6  *   var g1 = new Dygraph(...),
   7  *       g2 = new Dygraph(...),
   8  *       ...;
   9  *   var sync = Dygraph.synchronize(g1, g2, ...);
  10  *   // charts are now synchronized
  11  *   sync.detach();
  12  *   // charts are no longer synchronized
  13  *
  14  * You can set options using the last parameter, for example:
  15  *
  16  *   var sync = Dygraph.synchronize(g1, g2, g3, {
  17  *      selection: true,
  18  *      zoom: true
  19  *   });
  20  *
  21  * The default is to synchronize both of these.
  22  *
  23  * Instead of passing one Dygraph object as each parameter, you may also pass an
  24  * array of dygraphs:
  25  *
  26  *   var sync = Dygraph.synchronize([g1, g2, g3], {
  27  *      selection: false,
  28  *      zoom: true
  29  *   });
  30  *
  31  * You may also set `range: false` if you wish to only sync the x-axis.
  32  * The `range` option has no effect unless `zoom` is true (the default).
  33  */
  34 (function() {
  35 /* global Dygraph:false */
  36 'use strict';
  37
  38 Dygraph.synchronize = function(/* dygraphs..., opts */) {
  39   if (arguments.length === 0) {
  40     throw 'Invalid invocation of Dygraph.synchronize(). Need >= 1 argument.';
  41   }
  42
  43   var OPTIONS = ['selection', 'zoom', 'range'];
  44   var opts = {
  45     selection: true,
  46     zoom: true,
  47     range: true
  48   };
  49   var dygraphs = [];
  50
  51   var prevCallbacks = {
  52     draw: null,
  53     highlight: null,
  54     unhighlight: null
  55   };
  56
  57   var parseOpts = function(obj) {
  58     if (!(obj instanceof Object)) {
  59       throw 'Last argument must be either Dygraph or Object.';
  60     } else {
  61       for (var i = 0; i < OPTIONS.length; i++) {
  62         var optName = OPTIONS[i];
  63         if (obj.hasOwnProperty(optName)) opts[optName] = obj[optName];
  64       }
  65     }
  66   };
  67
  68   if (arguments[0] instanceof Dygraph) {
  69     // Arguments are Dygraph objects.
  70     for (var i = 0; i < arguments.length; i++) {
  71       if (arguments[i] instanceof Dygraph) {
  72         dygraphs.push(arguments[i]);
  73       } else {
  74         break;
  75       }
  76     }
  77     if (i < arguments.length - 1) {
  78       throw 'Invalid invocation of Dygraph.synchronize(). ' +
  79             'All but the last argument must be Dygraph objects.';
  80     } else if (i == arguments.length - 1) {
  81       parseOpts(arguments[arguments.length - 1]);
  82     }
  83   } else if (arguments[0].length) {
  84     // Invoked w/ list of dygraphs, options
  85     for (var i = 0; i < arguments[0].length; i++) {
  86       dygraphs.push(arguments[0][i]);
  87     }
  88     if (arguments.length == 2) {
  89       parseOpts(arguments[1]);
  90     } else if (arguments.length > 2) {
  91       throw 'Invalid invocation of Dygraph.synchronize(). ' +
  92             'Expected two arguments: array and optional options argument.';
  93     }  // otherwise arguments.length == 1, which is fine.
  94   } else {
  95     throw 'Invalid invocation of Dygraph.synchronize(). ' +
  96           'First parameter must be either Dygraph or list of Dygraphs.';
  97   }
  98
  99   if (dygraphs.length < 2) {
 100     throw 'Invalid invocation of Dygraph.synchronize(). ' +
 101           'Need two or more dygraphs to synchronize.';
 102   }
 103
 104   // Listen for draw, highlight, unhighlight callbacks.
 105   if (opts.zoom) {
 106     attachZoomHandlers(dygraphs, opts, prevCallbacks);
 107   }
 108
 109   if (opts.selection) {
 110     attachSelectionHandlers(dygraphs, prevCallbacks);
 111   }
 112
 113   return {
 114     detach: function() {
 115       for (var i = 0; i < dygraphs.length; i++) {
 116         var g = dygraphs[i];
 117         if (opts.zoom) {
 118           g.updateOptions({drawCallback: prevCallbacks.draw});
 119         }
 120         if (opts.selection) {
 121           g.updateOptions({
 122             highlightCallback: prevCallbacks.highlight,
 123             unhighlightCallback: prevCallbacks.unhighlight
 124           });
 125         }
 126       }
 127       // release references & make subsequent calls throw.
 128       dygraphs = null;
 129       opts = null;
 130     }
 131   };
 132 };
 133
 134 function attachZoomHandlers(gs, syncOpts, prevCallbacks) {
 135   var block = false;
 136   for (var i = 0; i < gs.length; i++) {
 137     var g = gs[i];
 138     prevCallbacks.draw = g.getFunctionOption('drawCallback');
 139     g.updateOptions({
 140       drawCallback: function(me, initial) {
 141         if (prevCallbacks.draw) prevCallbacks.draw(me, initial);
 142         if (block || initial) return;
 143         block = true;
 144         var opts = {
 145           dateWindow: me.xAxisRange()
 146         };
 147         if (syncOpts.range) opts.valueRange = me.yAxisRange();
 148
 149         for (var j = 0; j < gs.length; j++) {
 150           if (gs[j] == me) continue;
 151           gs[j].updateOptions(opts);
 152         }
 153         block = false;
 154       }
 155     }, false /* no need to redraw */);
 156   }
 157 }
 158
 159 function attachSelectionHandlers(gs, prevCallbacks) {
 160   var block = false;
 161   for (var i = 0; i < gs.length; i++) {
 162     var g = gs[i];
 163     prevCallbacks.highlight = g.getFunctionOption('highlightCallback');
 164     prevCallbacks.unhighlight = g.getFunctionOption('unhighlightCallback');
 165     g.updateOptions({
 166       highlightCallback: function(event, x, points, row, seriesName) {
 167         if (prevCallbacks.highlight) prevCallbacks.highlight(event, x, points, row, seriesName);
 168         if (block) return;
 169         block = true;
 170         var me = this;
 171         for (var i = 0; i < gs.length; i++) {
 172           if (me == gs[i]) continue;
 173           var idx = dygraphsBinarySearch(gs[i], x);
 174           if (idx !== null) {
 175             gs[i].setSelection(idx, seriesName);
 176           }
 177         }
 178         block = false;
 179       },
 180       unhighlightCallback: function(event) {
 181         if (prevCallbacks.unhighlight) prevCallbacks.unhighlight(event);
 182         if (block) return;
 183         block = true;
 184         var me = this;
 185         for (var i = 0; i < gs.length; i++) {
 186           if (me == gs[i]) continue;
 187           gs[i].clearSelection();
 188         }
 189         block = false;
 190       }
 191     });
 192   }
 193 }
 194
 195 // Returns the index corresponding to xVal, or null if there is none.
 196 function dygraphsBinarySearch(g, xVal) {
 197   var low = 0,
 198       high = g.numRows() - 1;
 199
 200   while (low < high) {
 201     var idx = (high + low) >> 1;
 202     var x = g.getValue(idx, 0);
 203     if (x < xVal) {
 204       low = idx + 1;
 205     } else if (x > xVal) {
 206       high = idx - 1;
 207     } else {
 208       return idx;
 209     }
 210   }
 211
 212   // TODO: give an option to find the closest point, i.e. not demand an exact match.
 213   return null;
 214 }
 215
 216 })();