dygraph-options.js

   1 /**
   2  * @fileoverview DygraphOptions is responsible for parsing and returning information about options.
   3  *
   4  * Still tightly coupled to Dygraphs, we could remove some of that, you know.
   5  */
   6
   7 "use strict";
   8
   9 /*
  10  * Interesting member variables:
  11  * dygraph_ - the graph.
  12  * global_ - global attributes (common among all graphs, AIUI)
  13  * user - attributes set by the user
  14  * yAxes_ - array of axis index to { series : [ series names ] , options : { axis-specific options. }
  15  * xAxis_ - { options : { axis-specific options. }
  16  * series_ - { seriesName -> { idx, yAxis, options }}
  17  * labels_ - used as mapping from index to series name.
  18  */
  19
  20 /**
  21  * This parses attributes into an object that can be easily queried.
  22  *
  23  * It doesn't necessarily mean that all options are available, specifically
  24  * if labels are not yet available, since those drive details of the per-series
  25  * and per-axis options.
  26  *
  27  * @param {Dyraph} dygraph The chart to which these options belong.
  28  * @constructor
  29  */
  30 var DygraphOptions = function(dygraph) {
  31   this.dygraph_ = dygraph;
  32   this.yAxes_ = [];
  33   this.xAxis_ = {};
  34   this.series_ = {};
  35
  36   // Once these two objects are initialized, you can call get();
  37   this.global_ = this.dygraph_.attrs_;
  38   this.user_ = this.dygraph_.user_attrs_ || {};
  39
  40   this.highlightSeries_ = this.get("highlightSeriesOpts") || {};
  41   this.reparseSeries();
  42 };
  43
  44 /*
  45  * Not optimal, but does the trick when you're only using two axes.
  46  * If we move to more axes, this can just become a function.
  47  */
  48 DygraphOptions.AXIS_STRING_MAPPINGS_ = {
  49   'y' : 0,
  50   'Y' : 0,
  51   'y1' : 0,
  52   'Y1' : 0,
  53   'y2' : 1,
  54   'Y2' : 1
  55 };
  56
  57 DygraphOptions.axisToIndex_ = function(axis) {
  58   if (typeof(axis) == "string") {
  59     if (DygraphOptions.AXIS_STRING_MAPPINGS_.hasOwnProperty(axis)) {
  60       return DygraphOptions.AXIS_STRING_MAPPINGS_[axis];
  61     }
  62     throw "Unknown axis : " + axis;
  63   }
  64   if (typeof(axis) == "number") {
  65     if (axis === 0 || axis === 1) {
  66       return axis;
  67     }
  68     throw "Dygraphs only supports two y-axes, indexed from 0-1.";
  69   }
  70   if (typeof(axis) == "object") {
  71     throw "Using objects for axis specification "
  72       + "is not supported inside the 'series' option.";
  73   }
  74   if (axis) {
  75     throw "Unknown axis : " + axis;
  76   }
  77   // No axis specification means axis 0.
  78   return 0;
  79 };
  80
  81 /**
  82  * Reparses options that are all related to series. This typically occurs when
  83  * options are either updated, or source data has been made avaialble.
  84  *
  85  * TODO(konigsberg): The method name is kind of weak; fix.
  86  */
  87 DygraphOptions.prototype.reparseSeries = function() {
  88   var labels = this.get("labels");
  89   if (!labels) {
  90     return; // -- can't do more for now, will parse after getting the labels.
  91   }
  92
  93   this.labels = labels.slice(1);
  94
  95   this.yAxes_ = [ { series : [], options : {}} ]; // Always one axis at least.
  96   this.xAxis_ = { options : {} };
  97   this.series_ = {};
  98
  99   // Traditionally, per-series options were specified right up there with the options. For instance
 100   // {
 101   //   labels: [ "X", "foo", "bar" ],
 102   //   pointSize: 3,
 103   //   foo : {}, // options for foo
 104   //   bar : {} // options for bar
 105   // }
 106   //
 107   // Moving forward, series really should be specified in the series element, separating them.
 108   // like so:
 109   //
 110   // {
 111   //   labels: [ "X", "foo", "bar" ],
 112   //   pointSize: 3,
 113   //   series : {
 114   //     foo : {}, // options for foo
 115   //     bar : {} // options for bar
 116   //   }
 117   // }
 118   //
 119   // So, if series is found, it's expected to contain per-series data, otherwise we fall
 120   // back.
 121   var oldStyleSeries = !this.user_["series"];
 122
 123   if (oldStyleSeries) {
 124     var axisId = 0; // 0-offset; there's always one.
 125     // Go through once, add all the series, and for those with {} axis options, add a new axis.
 126     for (var idx = 0; idx < this.labels.length; idx++) {
 127       var seriesName = this.labels[idx];
 128
 129       var optionsForSeries = this.user_[seriesName] || {};
 130
 131       var yAxis = 0;
 132       var axis = optionsForSeries["axis"];
 133       if (typeof(axis) == 'object') {
 134         yAxis = ++axisId;
 135         this.yAxes_[yAxis] = { series : [ seriesName ], options : axis };
 136       }
 137
 138       // Associate series without axis options with axis 0.
 139       if (!axis) { // undefined
 140         this.yAxes_[0].series.push(seriesName);
 141       }
 142
 143       this.series_[seriesName] = { idx: idx, yAxis: yAxis, options : optionsForSeries };
 144     }
 145
 146     // Go through one more time and assign series to an axis defined by another
 147     // series, e.g. { 'Y1: { axis: {} }, 'Y2': { axis: 'Y1' } }
 148     for (var idx = 0; idx < this.labels.length; idx++) {
 149       var seriesName = this.labels[idx];
 150       var optionsForSeries = this.series_[seriesName]["options"];
 151       var axis = optionsForSeries["axis"];
 152
 153       if (typeof(axis) == 'string') {
 154         if (!this.series_.hasOwnProperty(axis)) {
 155           this.dygraph_.error("Series " + seriesName + " wants to share a y-axis with " +
 156                      "series " + axis + ", which does not define its own axis.");
 157           return null;
 158         }
 159         var yAxis = this.series_[axis].yAxis;
 160         this.series_[seriesName].yAxis = yAxis;
 161         this.yAxes_[yAxis].series.push(seriesName);
 162       }
 163     }
 164   } else {
 165     for (var idx = 0; idx < this.labels.length; idx++) {
 166       var seriesName = this.labels[idx];
 167       var optionsForSeries = this.user_.series[seriesName] || {};
 168       var yAxis = DygraphOptions.axisToIndex_(optionsForSeries["axis"]);
 169
 170       this.series_[seriesName] = {
 171         idx: idx,
 172         yAxis: yAxis,
 173         options : optionsForSeries };
 174
 175       if (!this.yAxes_[yAxis]) {
 176         this.yAxes_[yAxis] =  { series : [ seriesName ], options : {} };
 177       } else {
 178         this.yAxes_[yAxis].series.push(seriesName);
 179       }
 180     }
 181   }
 182
 183   var axis_opts = this.user_["axes"] || {};
 184   Dygraph.update(this.yAxes_[0].options, axis_opts["y"] || {});
 185   if (this.yAxes_.length > 1) {
 186     Dygraph.update(this.yAxes_[1].options, axis_opts["y2"] || {});
 187   }
 188   Dygraph.update(this.xAxis_.options, axis_opts["x"] || {});
 189 };
 190
 191 /**
 192  * Get a global value.
 193  *
 194  * @param {string} name the name of the option.
 195  */
 196 DygraphOptions.prototype.get = function(name) {
 197   var result = this.getGlobalUser_(name);
 198   if (result != null) {
 199     return result;
 200   }
 201   return this.getGlobalDefault_(name);
 202 };
 203
 204 DygraphOptions.prototype.getGlobalUser_ = function(name) {
 205   if (this.user_.hasOwnProperty(name)) {
 206     return this.user_[name];
 207   }
 208   return null;
 209 };
 210
 211 DygraphOptions.prototype.getGlobalDefault_ = function(name) {
 212   if (this.global_.hasOwnProperty(name)) {
 213     return this.global_[name];
 214   }
 215   if (Dygraph.DEFAULT_ATTRS.hasOwnProperty(name)) {
 216     return Dygraph.DEFAULT_ATTRS[name];
 217   }
 218   return null;
 219 }
 220
 221 /**
 222  * Get a value for a specific axis. If there is no specific value for the axis,
 223  * the global value is returned.
 224  *
 225  * @param {string} name the name of the option.
 226  * @param {string|number} axis the axis to search. Can be the string representation
 227  * ("y", "y2") or the axis number (0, 1).
 228  */
 229 DygraphOptions.prototype.getForAxis = function(name, axis) {
 230   var axisIdx;
 231   var axisString;
 232
 233   // Since axis can be a number or a string, straighten everything out here.
 234   if (typeof(axis) == 'number') {
 235     axisIdx = axis;
 236     axisString = axisIdx == 0 ? "y" : "y2";
 237   } else {
 238     if (axis == "y1") { axis = "y"; } // Standardize on 'y'. Is this bad? I think so.
 239     if (axis == "y") {
 240       axisIdx = 0;
 241     } else if (axis == "y2") {
 242       axisIdx = 1;
 243     } else if (axis == "x") {
 244       axisIdx = -1; // simply a placeholder for below.
 245     } else {
 246       throw "Unknown axis " + axis;
 247     }
 248     axisString = axis;
 249   }
 250
 251   var userAxis = (axisIdx == -1) ? this.xAxis_ : this.yAxes_[axisIdx];
 252
 253   // Search the user-specified axis option first.
 254   if (userAxis) { // This condition could be removed if we always set up this.yAxes_ for y2.
 255     var axisOptions = userAxis.options;
 256     if (axisOptions.hasOwnProperty(name)) {
 257       return axisOptions[name];
 258     }
 259   }
 260
 261   // User-specified global options second.
 262   var result = this.getGlobalUser_(name);
 263   if (result != null) {
 264     return result;
 265   }
 266
 267   // Default axis options third.
 268   var defaultAxisOptions = Dygraph.DEFAULT_ATTRS.axes[axisString];
 269   if (defaultAxisOptions.hasOwnProperty(name)) {
 270     return defaultAxisOptions[name];
 271   }
 272
 273   // Default global options last.
 274   return this.getGlobalDefault_(name);
 275 };
 276
 277 /**
 278  * Get a value for a specific series. If there is no specific value for the series,
 279  * the value for the axis is returned (and afterwards, the global value.)
 280  *
 281  * @param {string} name the name of the option.
 282  * @param {string} series the series to search.
 283  */
 284 DygraphOptions.prototype.getForSeries = function(name, series) {
 285   // Honors indexes as series.
 286   if (series === this.dygraph_.highlightSet_) {
 287     if (this.highlightSeries_.hasOwnProperty(name)) {
 288       return this.highlightSeries_[name];
 289     }
 290   }
 291
 292   if (!this.series_.hasOwnProperty(series)) {
 293     throw "Unknown series: " + series;
 294   }
 295
 296   var seriesObj = this.series_[series];
 297   var seriesOptions = seriesObj["options"];
 298   if (seriesOptions.hasOwnProperty(name)) {
 299     return seriesOptions[name];
 300   }
 301
 302   return this.getForAxis(name, seriesObj["yAxis"]);
 303 };
 304
 305 /**
 306  * Returns the number of y-axes on the chart.
 307  * @return {Number} the number of axes.
 308  */
 309 DygraphOptions.prototype.numAxes = function() {
 310   return this.yAxes_.length;
 311 };
 312
 313 /**
 314  * Return the y-axis for a given series, specified by name.
 315  */
 316 DygraphOptions.prototype.axisForSeries = function(series) {
 317   return this.series_[series].yAxis;
 318 };
 319
 320 /**
 321  * Returns the options for the specified axis.
 322  */
 323 // TODO(konigsberg): this is y-axis specific. Support the x axis.
 324 DygraphOptions.prototype.axisOptions = function(yAxis) {
 325   return this.yAxes_[yAxis].options;
 326 };
 327
 328 /**
 329  * Return the series associated with an axis.
 330  */
 331 DygraphOptions.prototype.seriesForAxis = function(yAxis) {
 332   return this.yAxes_[yAxis].series;
 333 };
 334
 335 /**
 336  * Return the list of all series, in their columnar order.
 337  */
 338 DygraphOptions.prototype.seriesNames = function() {
 339   return this.labels_;
 340 };
 341
 342 /* Are we using this? */
 343 /**
 344  * Return the index of the specified series.
 345  * @param {string} series the series name.
 346  */
 347 DygraphOptions.prototype.indexOfSeries = function(series) {
 348   return this.series_[series].idx;
 349 };