Turn on more lint warnings; clear up some directives
[dygraphs.git] / dygraph-options.js
CommitLineData
c1780ad0 1/**
8e1ec00c
MF
2 * @license
3 * Copyright 2011 Dan Vanderkam (danvdk@gmail.com)
4 * MIT-licensed (http://opensource.org/licenses/MIT)
5 */
6
7/**
c1780ad0
RK
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
384bfa4a 13var DygraphOptions = (function() {
3ce712e6 14/*jshint strict:false */
384bfa4a 15
8887663f
DV
16// For "production" code, this gets set to false by uglifyjs.
17// Need to define it outside of "use strict", hence the nested IIFEs.
18if (typeof(DEBUG) === 'undefined') DEBUG=true;
19
20return (function() {
21
3ce712e6 22// TODO: remove this jshint directive & fix the warnings.
384bfa4a 23/*jshint sub:true */
83b0c192 24/*global Dygraph:false */
c1780ad0
RK
25"use strict";
26
27/*
e321ff2a 28 * Interesting member variables: (REMOVING THIS LIST AS I CLOSURIZE)
673a3b87 29 * global_ - global attributes (common among all graphs, AIUI)
ed30673a 30 * user - attributes set by the user
242a8bc8 31 * series_ - { seriesName -> { idx, yAxis, options }}
c1780ad0
RK
32 */
33
34/**
c1780ad0
RK
35 * This parses attributes into an object that can be easily queried.
36 *
5daa462d
RK
37 * It doesn't necessarily mean that all options are available, specifically
38 * if labels are not yet available, since those drive details of the per-series
39 * and per-axis options.
40 *
e321ff2a 41 * @param {Dygraph} dygraph The chart to which these options belong.
d67a4279 42 * @constructor
c1780ad0
RK
43 */
44var DygraphOptions = function(dygraph) {
e321ff2a
RK
45 /**
46 * The dygraph.
34655aba 47 * @type {!Dygraph}
e321ff2a 48 */
c1780ad0 49 this.dygraph_ = dygraph;
e321ff2a
RK
50
51 /**
52 * Array of axis index to { series : [ series names ] , options : { axis-specific options. }
72621b9a 53 * @type {Array.<{series : Array.<string>, options : Object}>} @private
e321ff2a 54 */
48dc3815 55 this.yAxes_ = [];
e321ff2a
RK
56
57 /**
2ed3480b
RK
58 * Contains x-axis specific options, which are stored in the options key.
59 * This matches the yAxes_ object structure (by being a dictionary with an
60 * options element) allowing for shared code.
61 * @type {options: Object} @private
e321ff2a 62 */
48dc3815 63 this.xAxis_ = {};
ed30673a 64 this.series_ = {};
c1780ad0 65
5daa462d 66 // Once these two objects are initialized, you can call get();
ed30673a
RK
67 this.global_ = this.dygraph_.attrs_;
68 this.user_ = this.dygraph_.user_attrs_ || {};
c1780ad0 69
e321ff2a
RK
70 /**
71 * A list of series in columnar order.
72 * @type {Array.<string>}
73 */
74 this.labels_ = [];
75
5daa462d 76 this.highlightSeries_ = this.get("highlightSeriesOpts") || {};
dd724e22 77 this.reparseSeries();
5daa462d 78};
34825ef5 79
e321ff2a 80/**
632bd78c
RK
81 * Not optimal, but does the trick when you're only using two axes.
82 * If we move to more axes, this can just become a function.
e321ff2a 83 *
34655aba 84 * @type {Object.<number>}
e321ff2a 85 * @private
632bd78c
RK
86 */
87DygraphOptions.AXIS_STRING_MAPPINGS_ = {
88 'y' : 0,
89 'Y' : 0,
90 'y1' : 0,
91 'Y1' : 0,
92 'y2' : 1,
93 'Y2' : 1
04f2bce6 94};
632bd78c 95
3f265488
LB
96/**
97 * @param {string|number} axis
98 * @private
99 */
632bd78c
RK
100DygraphOptions.axisToIndex_ = function(axis) {
101 if (typeof(axis) == "string") {
102 if (DygraphOptions.AXIS_STRING_MAPPINGS_.hasOwnProperty(axis)) {
103 return DygraphOptions.AXIS_STRING_MAPPINGS_[axis];
104 }
04f2bce6 105 throw "Unknown axis : " + axis;
632bd78c
RK
106 }
107 if (typeof(axis) == "number") {
04f2bce6 108 if (axis === 0 || axis === 1) {
632bd78c
RK
109 return axis;
110 }
04f2bce6 111 throw "Dygraphs only supports two y-axes, indexed from 0-1.";
632bd78c
RK
112 }
113 if (axis) {
114 throw "Unknown axis : " + axis;
115 }
116 // No axis specification means axis 0.
117 return 0;
118};
119
5daa462d
RK
120/**
121 * Reparses options that are all related to series. This typically occurs when
2fd143d3 122 * options are either updated, or source data has been made available.
5daa462d
RK
123 *
124 * TODO(konigsberg): The method name is kind of weak; fix.
125 */
34825ef5 126DygraphOptions.prototype.reparseSeries = function() {
9d562235
PF
127 var labels = this.get("labels");
128 if (!labels) {
129 return; // -- can't do more for now, will parse after getting the labels.
130 }
131
e321ff2a 132 this.labels_ = labels.slice(1);
c1780ad0 133
48dc3815
RK
134 this.yAxes_ = [ { series : [], options : {}} ]; // Always one axis at least.
135 this.xAxis_ = { options : {} };
ed30673a 136 this.series_ = {};
eb0da59f 137
73e953cd
RK
138 // Traditionally, per-series options were specified right up there with the options. For instance
139 // {
140 // labels: [ "X", "foo", "bar" ],
141 // pointSize: 3,
142 // foo : {}, // options for foo
143 // bar : {} // options for bar
144 // }
145 //
146 // Moving forward, series really should be specified in the series element, separating them.
147 // like so:
148 //
149 // {
150 // labels: [ "X", "foo", "bar" ],
151 // pointSize: 3,
152 // series : {
153 // foo : {}, // options for foo
154 // bar : {} // options for bar
155 // }
156 // }
157 //
158 // So, if series is found, it's expected to contain per-series data, otherwise we fall
159 // back.
632bd78c 160 var oldStyleSeries = !this.user_["series"];
9d562235 161
632bd78c
RK
162 if (oldStyleSeries) {
163 var axisId = 0; // 0-offset; there's always one.
164 // Go through once, add all the series, and for those with {} axis options, add a new axis.
e321ff2a
RK
165 for (var idx = 0; idx < this.labels_.length; idx++) {
166 var seriesName = this.labels_[idx];
9d562235 167
632bd78c 168 var optionsForSeries = this.user_[seriesName] || {};
9d562235 169
632bd78c
RK
170 var yAxis = 0;
171 var axis = optionsForSeries["axis"];
172 if (typeof(axis) == 'object') {
173 yAxis = ++axisId;
48dc3815 174 this.yAxes_[yAxis] = { series : [ seriesName ], options : axis };
632bd78c 175 }
c1780ad0 176
6ad8b6a4
RK
177 // Associate series without axis options with axis 0.
178 if (!axis) { // undefined
48dc3815 179 this.yAxes_[0].series.push(seriesName);
6ad8b6a4 180 }
c1780ad0 181
632bd78c
RK
182 this.series_[seriesName] = { idx: idx, yAxis: yAxis, options : optionsForSeries };
183 }
9d562235 184
632bd78c
RK
185 // Go through one more time and assign series to an axis defined by another
186 // series, e.g. { 'Y1: { axis: {} }, 'Y2': { axis: 'Y1' } }
e321ff2a
RK
187 for (var idx = 0; idx < this.labels_.length; idx++) {
188 var seriesName = this.labels_[idx];
9d562235 189 var optionsForSeries = this.series_[seriesName]["options"];
632bd78c 190 var axis = optionsForSeries["axis"];
9d562235 191
632bd78c
RK
192 if (typeof(axis) == 'string') {
193 if (!this.series_.hasOwnProperty(axis)) {
8a68db7d 194 console.error("Series " + seriesName + " wants to share a y-axis with " +
632bd78c 195 "series " + axis + ", which does not define its own axis.");
e1119361 196 return;
632bd78c 197 }
6ad8b6a4
RK
198 var yAxis = this.series_[axis].yAxis;
199 this.series_[seriesName].yAxis = yAxis;
48dc3815 200 this.yAxes_[yAxis].series.push(seriesName);
632bd78c
RK
201 }
202 }
203 } else {
e321ff2a
RK
204 for (var idx = 0; idx < this.labels_.length; idx++) {
205 var seriesName = this.labels_[idx];
632bd78c
RK
206 var optionsForSeries = this.user_.series[seriesName] || {};
207 var yAxis = DygraphOptions.axisToIndex_(optionsForSeries["axis"]);
c1780ad0 208
632bd78c
RK
209 this.series_[seriesName] = {
210 idx: idx,
211 yAxis: yAxis,
212 options : optionsForSeries };
c1780ad0 213
48dc3815
RK
214 if (!this.yAxes_[yAxis]) {
215 this.yAxes_[yAxis] = { series : [ seriesName ], options : {} };
6ad8b6a4 216 } else {
48dc3815 217 this.yAxes_[yAxis].series.push(seriesName);
c1780ad0 218 }
c1780ad0
RK
219 }
220 }
221
6ad8b6a4 222 var axis_opts = this.user_["axes"] || {};
48dc3815
RK
223 Dygraph.update(this.yAxes_[0].options, axis_opts["y"] || {});
224 if (this.yAxes_.length > 1) {
9d562235 225 Dygraph.update(this.yAxes_[1].options, axis_opts["y2"] || {});
c1780ad0 226 }
48dc3815 227 Dygraph.update(this.xAxis_.options, axis_opts["x"] || {});
8887663f
DV
228
229 if (DEBUG) this.validateOptions_();
c1780ad0
RK
230};
231
5daa462d
RK
232/**
233 * Get a global value.
234 *
a4aceb34 235 * @param {string} name the name of the option.
5daa462d
RK
236 */
237DygraphOptions.prototype.get = function(name) {
d574a45e 238 var result = this.getGlobalUser_(name);
2e3d8088 239 if (result !== null) {
d574a45e
RK
240 return result;
241 }
242 return this.getGlobalDefault_(name);
243};
244
245DygraphOptions.prototype.getGlobalUser_ = function(name) {
ed30673a
RK
246 if (this.user_.hasOwnProperty(name)) {
247 return this.user_[name];
c1780ad0 248 }
d574a45e
RK
249 return null;
250};
251
252DygraphOptions.prototype.getGlobalDefault_ = function(name) {
ed30673a
RK
253 if (this.global_.hasOwnProperty(name)) {
254 return this.global_[name];
c1780ad0 255 }
d574a45e
RK
256 if (Dygraph.DEFAULT_ATTRS.hasOwnProperty(name)) {
257 return Dygraph.DEFAULT_ATTRS[name];
258 }
c1780ad0 259 return null;
83b0c192 260};
c1780ad0 261
5daa462d
RK
262/**
263 * Get a value for a specific axis. If there is no specific value for the axis,
264 * the global value is returned.
265 *
a4aceb34
RK
266 * @param {string} name the name of the option.
267 * @param {string|number} axis the axis to search. Can be the string representation
5daa462d
RK
268 * ("y", "y2") or the axis number (0, 1).
269 */
270DygraphOptions.prototype.getForAxis = function(name, axis) {
48dc3815
RK
271 var axisIdx;
272 var axisString;
273
274 // Since axis can be a number or a string, straighten everything out here.
5daa462d
RK
275 if (typeof(axis) == 'number') {
276 axisIdx = axis;
2e3d8088 277 axisString = axisIdx === 0 ? "y" : "y2";
5daa462d 278 } else {
48dc3815
RK
279 if (axis == "y1") { axis = "y"; } // Standardize on 'y'. Is this bad? I think so.
280 if (axis == "y") {
281 axisIdx = 0;
282 } else if (axis == "y2") {
283 axisIdx = 1;
284 } else if (axis == "x") {
285 axisIdx = -1; // simply a placeholder for below.
286 } else {
287 throw "Unknown axis " + axis;
288 }
289 axisString = axis;
5daa462d 290 }
48dc3815
RK
291
292 var userAxis = (axisIdx == -1) ? this.xAxis_ : this.yAxes_[axisIdx];
293
d574a45e 294 // Search the user-specified axis option first.
48dc3815
RK
295 if (userAxis) { // This condition could be removed if we always set up this.yAxes_ for y2.
296 var axisOptions = userAxis.options;
d574a45e
RK
297 if (axisOptions.hasOwnProperty(name)) {
298 return axisOptions[name];
299 }
300 }
c1780ad0 301
d574a45e 302 // User-specified global options second.
5b9b2142
RK
303 // But, hack, ignore globally-specified 'logscale' for 'x' axis declaration.
304 if (!(axis === 'x' && name === 'logscale')) {
305 var result = this.getGlobalUser_(name);
306 if (result !== null) {
307 return result;
308 }
c1780ad0 309 }
d574a45e 310 // Default axis options third.
d574a45e
RK
311 var defaultAxisOptions = Dygraph.DEFAULT_ATTRS.axes[axisString];
312 if (defaultAxisOptions.hasOwnProperty(name)) {
313 return defaultAxisOptions[name];
314 }
315
316 // Default global options last.
317 return this.getGlobalDefault_(name);
5daa462d 318};
c1780ad0 319
5daa462d
RK
320/**
321 * Get a value for a specific series. If there is no specific value for the series,
322 * the value for the axis is returned (and afterwards, the global value.)
323 *
a4aceb34 324 * @param {string} name the name of the option.
8e19509a 325 * @param {string} series the series to search.
5daa462d
RK
326 */
327DygraphOptions.prototype.getForSeries = function(name, series) {
c1780ad0 328 // Honors indexes as series.
3f265488 329 if (series === this.dygraph_.getHighlightSeries()) {
ed30673a
RK
330 if (this.highlightSeries_.hasOwnProperty(name)) {
331 return this.highlightSeries_[name];
332 }
333 }
334
8e19509a 335 if (!this.series_.hasOwnProperty(series)) {
c1780ad0
RK
336 throw "Unknown series: " + series;
337 }
338
8e19509a 339 var seriesObj = this.series_[series];
c1780ad0
RK
340 var seriesOptions = seriesObj["options"];
341 if (seriesOptions.hasOwnProperty(name)) {
342 return seriesOptions[name];
343 }
ed30673a 344
5daa462d
RK
345 return this.getForAxis(name, seriesObj["yAxis"]);
346};
c1780ad0 347
673a3b87
RK
348/**
349 * Returns the number of y-axes on the chart.
e321ff2a 350 * @return {number} the number of axes.
673a3b87
RK
351 */
352DygraphOptions.prototype.numAxes = function() {
48dc3815 353 return this.yAxes_.length;
04f2bce6 354};
16f00742
RK
355
356/**
357 * Return the y-axis for a given series, specified by name.
358 */
8e19509a
RK
359DygraphOptions.prototype.axisForSeries = function(series) {
360 return this.series_[series].yAxis;
04f2bce6 361};
16f00742
RK
362
363/**
364 * Returns the options for the specified axis.
365 */
48dc3815 366// TODO(konigsberg): this is y-axis specific. Support the x axis.
16f00742 367DygraphOptions.prototype.axisOptions = function(yAxis) {
48dc3815 368 return this.yAxes_[yAxis].options;
04f2bce6 369};
16f00742
RK
370
371/**
372 * Return the series associated with an axis.
373 */
374DygraphOptions.prototype.seriesForAxis = function(yAxis) {
48dc3815 375 return this.yAxes_[yAxis].series;
04f2bce6 376};
6ad8b6a4
RK
377
378/**
379 * Return the list of all series, in their columnar order.
380 */
381DygraphOptions.prototype.seriesNames = function() {
382 return this.labels_;
04f2bce6 383};
6ad8b6a4 384
8887663f
DV
385if (DEBUG) {
386
387/**
388 * Validate all options.
389 * This requires Dygraph.OPTIONS_REFERENCE, which is only available in debug builds.
390 * @private
391 */
392DygraphOptions.prototype.validateOptions_ = function() {
393 if (typeof Dygraph.OPTIONS_REFERENCE === 'undefined') {
394 throw 'Called validateOptions_ in prod build.';
395 }
396
397 var that = this;
398 var validateOption = function(optionName) {
399 if (!Dygraph.OPTIONS_REFERENCE[optionName]) {
400 that.warnInvalidOption_(optionName);
401 }
402 };
403
404 var optionsDicts = [this.xAxis_.options,
405 this.yAxes_[0].options,
406 this.yAxes_[1] && this.yAxes_[1].options,
407 this.global_,
408 this.user_,
409 this.highlightSeries_];
b3cb0794
DV
410 var names = this.seriesNames();
411 for (var i = 0; i < names.length; i++) {
412 var name = names[i];
413 if (this.series_.hasOwnProperty(name)) {
414 optionsDicts.push(this.series_[name].options);
415 }
416 }
8887663f
DV
417 for (var i = 0; i < optionsDicts.length; i++) {
418 var dict = optionsDicts[i];
419 if (!dict) continue;
420 for (var optionName in dict) {
421 if (dict.hasOwnProperty(optionName)) {
422 validateOption(optionName);
423 }
424 }
425 }
426};
427
428var WARNINGS = {}; // Only show any particular warning once.
429
430/**
431 * Logs a warning about invalid options.
432 * TODO: make this throw for testing
433 * @private
434 */
435DygraphOptions.prototype.warnInvalidOption_ = function(optionName) {
436 if (!WARNINGS[optionName]) {
ac3070f8 437 WARNINGS[optionName] = true;
8887663f
DV
438 var isSeries = (this.labels_.indexOf(optionName) >= 0);
439 if (isSeries) {
440 console.warn('Use new-style per-series options (saw ' + optionName + ' as top-level options key). See http://bit.ly/1tceaJs');
441 } else {
442 console.warn('Unknown option ' + optionName + ' (full list of options at dygraphs.com/options.html');
ac3070f8 443 throw "invalid option " + optionName;
8887663f 444 }
8887663f
DV
445 }
446};
447
b3cb0794
DV
448// Reset list of previously-shown warnings. Used for testing.
449DygraphOptions.resetWarnings_ = function() {
450 WARNINGS = {};
451};
452
8887663f
DV
453}
454
384bfa4a
DV
455return DygraphOptions;
456
457})();
8887663f 458})();