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