dygraph-options.js

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