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