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