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