Merge branch 'master' into remove-old-options
[dygraphs.git] / dygraph-options.js
... / ...
CommitLineData
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.
12 * global_ - global attributes (common among all graphs, AIUI)
13 * user - attributes set by the user
14 * axes_ - array of axis index to { series : [ series names ] , options : { axis-specific options. }
15 * series_ - { seriesName -> { idx, yAxis, options }}
16 * labels_ - used as mapping from index to series name.
17 */
18
19/**
20 * This parses attributes into an object that can be easily queried.
21 *
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 *
26 * @param {Dyraph} dygraph The chart to which these options belong.
27 * @constructor
28 */
29var DygraphOptions = function(dygraph) {
30 this.dygraph_ = dygraph;
31 this.axes_ = [];
32 this.series_ = {};
33
34 // Once these two objects are initialized, you can call get();
35 this.global_ = this.dygraph_.attrs_;
36 this.user_ = this.dygraph_.user_attrs_ || {};
37
38 this.highlightSeries_ = this.get("highlightSeriesOpts") || {};
39 // Get a list of series names.
40
41 var labels = this.get("labels");
42 if (!labels) {
43 return; // -- can't do more for now, will parse after getting the labels.
44 }
45
46 this.reparseSeries();
47};
48
49/**
50 * Reparses options that are all related to series. This typically occurs when
51 * options are either updated, or source data has been made avaialble.
52 *
53 * TODO(konigsberg): The method name is kind of weak; fix.
54 */
55DygraphOptions.prototype.reparseSeries = function() {
56 this.labels = this.get("labels").slice(1);
57
58 this.axes_ = [ { series : [], options : {}} ]; // Always one axis at least.
59 this.series_ = {};
60
61 var axisId = 0; // 0-offset; there's always one.
62 // Go through once, add all the series, and for those with {} axis options, add a new axis.
63 for (var idx = 0; idx < this.labels.length; idx++) {
64 var seriesName = this.labels[idx];
65
66 var optionsForSeries = this.user_[seriesName] || {};
67 var yAxis = 0;
68
69 var axis = optionsForSeries["axis"];
70 if (typeof(axis) == 'object') {
71 yAxis = ++axisId;
72 this.axes_[yAxis] = { series : [ seriesName ], options : axis };
73 }
74
75 // Associate series without axis options with axis 0.
76 if (!axis) { // undefined
77 this.axes_[0].series.push(seriesName);
78 }
79
80 this.series_[seriesName] = { idx: idx, yAxis: yAxis, options : optionsForSeries };
81 }
82
83 // Go through one more time and assign series to an axis defined by another
84 // series, e.g. { 'Y1: { axis: {} }, 'Y2': { axis: 'Y1' } }
85 for (var idx = 0; idx < this.labels.length; idx++) {
86 var seriesName = this.labels[idx];
87 var optionsForSeries = this.series_[seriesName]["options"];
88 var axis = optionsForSeries["axis"];
89
90 if (typeof(axis) == 'string') {
91 if (!this.series_.hasOwnProperty(axis)) {
92 this.dygraph_.error("Series " + seriesName + " wants to share a y-axis with " +
93 "series " + axis + ", which does not define its own axis.");
94 return null;
95 }
96 var yAxis = this.series_[axis].yAxis;
97 this.series_[seriesName].yAxis = yAxis;
98 this.axes_[yAxis].series.push(seriesName);
99 }
100 }
101
102 // This doesn't support reading from the 'x' axis, only 'y' and 'y2.
103 // Read from the global "axes" option.
104 if (this.user_.hasOwnProperty("axes")) {
105 var axis_opts = this.user_.axes;
106
107 if (axis_opts.hasOwnProperty("y")) {
108 Dygraph.update(this.axes_[0].options, axis_opts.y);
109 }
110
111 if (axis_opts.hasOwnProperty("y2")) {
112 this.axes_[1] = this.axes_[1] || {}; // FIX
113 Dygraph.update(this.axes_[1].options, axis_opts.y2);
114 }
115 }
116};
117
118/**
119 * Get a global value.
120 *
121 * @param {String} name the name of the option.
122 */
123DygraphOptions.prototype.get = function(name) {
124 if (this.user_.hasOwnProperty(name)) {
125 return this.user_[name];
126 }
127 if (this.global_.hasOwnProperty(name)) {
128 return this.global_[name];
129 }
130 return null;
131};
132
133/**
134 * Get a value for a specific axis. If there is no specific value for the axis,
135 * the global value is returned.
136 *
137 * @param {String} name the name of the option.
138 * @param {String|number} axis the axis to search. Can be the string representation
139 * ("y", "y2") or the axis number (0, 1).
140 */
141DygraphOptions.prototype.getForAxis = function(name, axis) {
142 var axisIdx = 0;
143 if (typeof(axis) == 'number') {
144 axisIdx = axis;
145 } else {
146 // TODO(konigsberg): Accept only valid axis strings?
147 axisIdx = (axis == "y2") ? 1 : 0;
148 }
149
150 var axisOptions = this.axes_[axisIdx].options;
151 if (axisOptions.hasOwnProperty(name)) {
152 return axisOptions[name];
153 }
154 return this.get(name);
155};
156
157/**
158 * Get a value for a specific series. If there is no specific value for the series,
159 * the value for the axis is returned (and afterwards, the global value.)
160 *
161 * @param {String} name the name of the option.
162 * @param {String|number} series the series to search. Can be the string representation
163 * or 0-offset series number.
164 */
165DygraphOptions.prototype.getForSeries = function(name, series) {
166 // Honors indexes as series.
167 var seriesName = (typeof(series) == "number") ? this.labels[series] : series;
168
169 if (seriesName === this.dygraph_.highlightSet_) {
170 if (this.highlightSeries_.hasOwnProperty(name)) {
171 return this.highlightSeries_[name];
172 }
173 }
174
175 if (!this.series_.hasOwnProperty(seriesName)) {
176 throw "Unknown series: " + series;
177 }
178
179 var seriesObj = this.series_[seriesName];
180 var seriesOptions = seriesObj["options"];
181 if (seriesOptions.hasOwnProperty(name)) {
182 return seriesOptions[name];
183 }
184
185 return this.getForAxis(name, seriesObj["yAxis"]);
186};
187
188/**
189 * Returns the number of y-axes on the chart.
190 * @return {Number} the number of axes.
191 */
192DygraphOptions.prototype.numAxes = function() {
193 return this.axes_.length;
194}
195
196/**
197 * Return the y-axis for a given series, specified by name.
198 */
199DygraphOptions.prototype.axisForSeries = function(seriesName) {
200 return this.series_[seriesName].yAxis;
201}
202
203/**
204 * Returns the options for the specified axis.
205 */
206DygraphOptions.prototype.axisOptions = function(yAxis) {
207 return this.axes_[yAxis].options;
208}
209
210/**
211 * Return the series associated with an axis.
212 */
213DygraphOptions.prototype.seriesForAxis = function(yAxis) {
214 return this.axes_[yAxis].series;
215}