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