3 * Copyright 2011 Dan Vanderkam (danvdk@gmail.com)
4 * MIT-licensed (http://opensource.org/licenses/MIT)
8 * @fileoverview DygraphOptions is responsible for parsing and returning information about options.
10 * Still tightly coupled to Dygraphs, we could remove some of that, you know.
13 var DygraphOptions
= (function() {
14 /*jshint strict:false */
16 // For "production" code, this gets set to false by uglifyjs.
17 // Need to define it outside of "use strict", hence the nested IIFEs.
18 if (typeof(DEBUG
) === 'undefined') DEBUG
=true;
22 // TODO: remove this jshint directive & fix the warnings.
24 /*global Dygraph:false */
28 * Interesting member variables: (REMOVING THIS LIST AS I CLOSURIZE)
29 * global_ - global attributes (common among all graphs, AIUI)
30 * user - attributes set by the user
31 * series_ - { seriesName -> { idx, yAxis, options }}
35 * This parses attributes into an object that can be easily queried.
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.
41 * @param {Dygraph} dygraph The chart to which these options belong.
44 var DygraphOptions
= function(dygraph
) {
49 this.dygraph_
= dygraph
;
52 * Array of axis index to { series : [ series names ] , options : { axis-specific options. }
53 * @type {Array.<{series : Array.<string>, options : Object}>} @private
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
66 // Once these two objects are initialized, you can call get();
67 this.global_
= this.dygraph_
.attrs_
;
68 this.user_
= this.dygraph_
.user_attrs_
|| {};
71 * A list of series in columnar order.
72 * @type {Array.<string>}
76 this.highlightSeries_
= this.get("highlightSeriesOpts") || {};
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.
84 * @type {Object.<number>}
87 DygraphOptions
.AXIS_STRING_MAPPINGS_
= {
97 * @param {string|number} axis
100 DygraphOptions
.axisToIndex_
= function(axis
) {
101 if (typeof(axis
) == "string") {
102 if (DygraphOptions
.AXIS_STRING_MAPPINGS_
.hasOwnProperty(axis
)) {
103 return DygraphOptions
.AXIS_STRING_MAPPINGS_
[axis
];
105 throw "Unknown axis : " + axis
;
107 if (typeof(axis
) == "number") {
108 if (axis
=== 0 || axis
=== 1) {
111 throw "Dygraphs only supports two y-axes, indexed from 0-1.";
114 throw "Unknown axis : " + axis
;
116 // No axis specification means axis 0.
121 * Reparses options that are all related to series. This typically occurs when
122 * options are either updated, or source data has been made available.
124 * TODO(konigsberg): The method name is kind of weak; fix.
126 DygraphOptions
.prototype.reparseSeries
= function() {
127 var labels
= this.get("labels");
129 return; // -- can't do more for now, will parse after getting the labels.
132 this.labels_
= labels
.slice(1);
134 this.yAxes_
= [ { series
: [], options
: {}} ]; // Always one axis at least.
135 this.xAxis_
= { options
: {} };
138 // Traditionally, per-series options were specified right up there with the options. For instance
140 // labels: [ "X", "foo", "bar" ],
142 // foo : {}, // options
for foo
143 // bar : {} // options
for bar
146 // Moving forward, series really should be specified in the series element, separating them.
150 // labels: [ "X", "foo", "bar" ],
153 // foo : {}, // options
for foo
154 // bar : {} // options
for bar
158 // So, if series is found, it's expected to contain per-series data, otherwise we fall
160 var oldStyleSeries
= !this.user_
["series"];
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.
165 for (var idx
= 0; idx
< this.labels_
.length
; idx
++) {
166 var seriesName
= this.labels_
[idx
];
168 var optionsForSeries
= this.user_
[seriesName
] || {};
171 var axis
= optionsForSeries
["axis"];
172 if (typeof(axis
) == 'object') {
174 this.yAxes_
[yAxis
] = { series
: [ seriesName
], options
: axis
};
177 // Associate series without axis options with axis 0.
178 if (!axis
) { // undefined
179 this.yAxes_
[0].series
.push(seriesName
);
182 this.series_
[seriesName
] = { idx
: idx
, yAxis
: yAxis
, options
: optionsForSeries
};
185 // Go through one more time and assign series to an axis defined by another
186 // series, e.g. { 'Y1: { axis: {} }, 'Y2': { axis: 'Y1' } }
187 for (var idx
= 0; idx
< this.labels_
.length
; idx
++) {
188 var seriesName
= this.labels_
[idx
];
189 var optionsForSeries
= this.series_
[seriesName
]["options"];
190 var axis
= optionsForSeries
["axis"];
192 if (typeof(axis
) == 'string') {
193 if (!this.series_
.hasOwnProperty(axis
)) {
194 console
.error("Series " + seriesName
+ " wants to share a y-axis with " +
195 "series " + axis
+ ", which does not define its own axis.");
198 var yAxis
= this.series_
[axis
].yAxis
;
199 this.series_
[seriesName
].yAxis
= yAxis
;
200 this.yAxes_
[yAxis
].series
.push(seriesName
);
204 for (var idx
= 0; idx
< this.labels_
.length
; idx
++) {
205 var seriesName
= this.labels_
[idx
];
206 var optionsForSeries
= this.user_
.series
[seriesName
] || {};
207 var yAxis
= DygraphOptions
.axisToIndex_(optionsForSeries
["axis"]);
209 this.series_
[seriesName
] = {
212 options
: optionsForSeries
};
214 if (!this.yAxes_
[yAxis
]) {
215 this.yAxes_
[yAxis
] = { series
: [ seriesName
], options
: {} };
217 this.yAxes_
[yAxis
].series
.push(seriesName
);
222 var axis_opts
= this.user_
["axes"] || {};
223 Dygraph
.update(this.yAxes_
[0].options
, axis_opts
["y"] || {});
224 if (this.yAxes_
.length
> 1) {
225 Dygraph
.update(this.yAxes_
[1].options
, axis_opts
["y2"] || {});
227 Dygraph
.update(this.xAxis_
.options
, axis_opts
["x"] || {});
229 if (DEBUG
) this.validateOptions_();
233 * Get a global value.
235 * @param {string} name the name of the option.
237 DygraphOptions
.prototype.get
= function(name
) {
238 var result
= this.getGlobalUser_(name
);
239 if (result
!== null) {
242 return this.getGlobalDefault_(name
);
245 DygraphOptions
.prototype.getGlobalUser_
= function(name
) {
246 if (this.user_
.hasOwnProperty(name
)) {
247 return this.user_
[name
];
252 DygraphOptions
.prototype.getGlobalDefault_
= function(name
) {
253 if (this.global_
.hasOwnProperty(name
)) {
254 return this.global_
[name
];
256 if (Dygraph
.DEFAULT_ATTRS
.hasOwnProperty(name
)) {
257 return Dygraph
.DEFAULT_ATTRS
[name
];
263 * Get a value for a specific axis. If there is no specific value for the axis,
264 * the global value is returned.
266 * @param {string} name the name of the option.
267 * @param {string|number} axis the axis to search. Can be the string representation
268 * ("y", "y2") or the axis number (0, 1).
270 DygraphOptions
.prototype.getForAxis
= function(name
, axis
) {
274 // Since axis can be a number or a string, straighten everything out here.
275 if (typeof(axis
) == 'number') {
277 axisString
= axisIdx
=== 0 ? "y" : "y2";
279 if (axis
== "y1") { axis
= "y"; } // Standardize on 'y'. Is this bad? I think so.
282 } else if (axis
== "y2") {
284 } else if (axis
== "x") {
285 axisIdx
= -1; // simply a placeholder for below.
287 throw "Unknown axis " + axis
;
292 var userAxis
= (axisIdx
== -1) ? this.xAxis_
: this.yAxes_
[axisIdx
];
294 // Search the user-specified axis option first.
295 if (userAxis
) { // This condition could be removed if we always set up this.yAxes_ for y2.
296 var axisOptions
= userAxis
.options
;
297 if (axisOptions
.hasOwnProperty(name
)) {
298 return axisOptions
[name
];
302 // User-specified global options second.
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) {
310 // Default axis options third.
311 var defaultAxisOptions
= Dygraph
.DEFAULT_ATTRS
.axes
[axisString
];
312 if (defaultAxisOptions
.hasOwnProperty(name
)) {
313 return defaultAxisOptions
[name
];
316 // Default global options last.
317 return this.getGlobalDefault_(name
);
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.)
324 * @param {string} name the name of the option.
325 * @param {string} series the series to search.
327 DygraphOptions
.prototype.getForSeries
= function(name
, series
) {
328 // Honors indexes as series.
329 if (series
=== this.dygraph_
.getHighlightSeries()) {
330 if (this.highlightSeries_
.hasOwnProperty(name
)) {
331 return this.highlightSeries_
[name
];
335 if (!this.series_
.hasOwnProperty(series
)) {
336 throw "Unknown series: " + series
;
339 var seriesObj
= this.series_
[series
];
340 var seriesOptions
= seriesObj
["options"];
341 if (seriesOptions
.hasOwnProperty(name
)) {
342 return seriesOptions
[name
];
345 return this.getForAxis(name
, seriesObj
["yAxis"]);
349 * Returns the number of y-axes on the chart.
350 * @return {number} the number of axes.
352 DygraphOptions
.prototype.numAxes
= function() {
353 return this.yAxes_
.length
;
357 * Return the y-axis for a given series, specified by name.
359 DygraphOptions
.prototype.axisForSeries
= function(series
) {
360 return this.series_
[series
].yAxis
;
364 * Returns the options for the specified axis.
366 // TODO(konigsberg): this is y-axis specific. Support the x axis.
367 DygraphOptions
.prototype.axisOptions
= function(yAxis
) {
368 return this.yAxes_
[yAxis
].options
;
372 * Return the series associated with an axis.
374 DygraphOptions
.prototype.seriesForAxis
= function(yAxis
) {
375 return this.yAxes_
[yAxis
].series
;
379 * Return the list of all series, in their columnar order.
381 DygraphOptions
.prototype.seriesNames
= function() {
388 * Validate all options.
389 * This requires Dygraph.OPTIONS_REFERENCE, which is only available in debug builds.
392 DygraphOptions
.prototype.validateOptions_
= function() {
393 if (typeof Dygraph
.OPTIONS_REFERENCE
=== 'undefined') {
394 throw 'Called validateOptions_ in prod build.';
398 var validateOption
= function(optionName
) {
399 if (!Dygraph
.OPTIONS_REFERENCE
[optionName
]) {
400 that
.warnInvalidOption_(optionName
);
404 var optionsDicts
= [this.xAxis_
.options
,
405 this.yAxes_
[0].options
,
406 this.yAxes_
[1] && this.yAxes_
[1].options
,
409 this.highlightSeries_
];
410 var names
= this.seriesNames();
411 for (var i
= 0; i
< names
.length
; i
++) {
413 if (this.series_
.hasOwnProperty(name
)) {
414 optionsDicts
.push(this.series_
[name
].options
);
417 for (var i
= 0; i
< optionsDicts
.length
; i
++) {
418 var dict
= optionsDicts
[i
];
420 for (var optionName
in dict
) {
421 if (dict
.hasOwnProperty(optionName
)) {
422 validateOption(optionName
);
428 var WARNINGS
= {}; // Only show any particular warning once.
431 * Logs a warning about invalid options.
432 * TODO: make this throw for testing
435 DygraphOptions
.prototype.warnInvalidOption_
= function(optionName
) {
436 if (!WARNINGS
[optionName
]) {
437 WARNINGS
[optionName
] = true;
438 var isSeries
= (this.labels_
.indexOf(optionName
) >= 0);
440 console
.warn('Use new-style per-series options (saw ' + optionName
+ ' as top-level options key). See http://bit.ly/1tceaJs');
442 console
.warn('Unknown option ' + optionName
+ ' (full list of options at dygraphs.com/options.html');
443 throw "invalid option " + optionName
;
448 // Reset list of previously-shown warnings. Used for testing.
449 DygraphOptions
.resetWarnings_
= function() {
455 return DygraphOptions
;