bb869491125bcbba192529261be249ac59baccfb
[dygraphs.git] / plugins / legend.js
1 /**
2 * @license
3 * Copyright 2012 Dan Vanderkam (danvdk@gmail.com)
4 * MIT-licensed (http://opensource.org/licenses/MIT)
5 */
6 /*global Dygraph:false */
7
8 Dygraph.Plugins.Legend = (function() {
9 /*
10 Current bits of jankiness:
11 - Uses two private APIs:
12 1. Dygraph.optionsViewForAxis_
13 2. dygraph.plotter_.area
14 - Registers for a "predraw" event, which should be renamed.
15 - I call calculateEmWidthInDiv more often than needed.
16 */
17
18 /*global Dygraph:false */
19 "use strict";
20
21
22 /**
23 * Creates the legend, which appears when the user hovers over the chart.
24 * The legend can be either a user-specified or generated div.
25 *
26 * @constructor
27 */
28 var legend = function() {
29 this.legend_div_ = null;
30 this.is_generated_div_ = false; // do we own this div, or was it user-specified?
31 };
32
33 legend.prototype.toString = function() {
34 return "Legend Plugin";
35 };
36
37 // (defined below)
38 var generateLegendDashHTML;
39
40 /**
41 * This is called during the dygraph constructor, after options have been set
42 * but before the data is available.
43 *
44 * Proper tasks to do here include:
45 * - Reading your own options
46 * - DOM manipulation
47 * - Registering event listeners
48 *
49 * @param {Dygraph} g Graph instance.
50 * @return {object.<string, function(ev)>} Mapping of event names to callbacks.
51 */
52 legend.prototype.activate = function(g) {
53 var div;
54 var divWidth = g.getOption('labelsDivWidth');
55
56 var userLabelsDiv = g.getOption('labelsDiv');
57 if (userLabelsDiv && null !== userLabelsDiv) {
58 if (typeof(userLabelsDiv) == "string" || userLabelsDiv instanceof String) {
59 div = document.getElementById(userLabelsDiv);
60 } else {
61 div = userLabelsDiv;
62 }
63 } else {
64 // Default legend styles. These can be overridden in CSS by adding
65 // "!important" after your rule, e.g. "left: 30px !important;"
66 var messagestyle = {
67 "position": "absolute",
68 "fontSize": "14px",
69 "zIndex": 10,
70 "width": divWidth + "px",
71 "top": "0px",
72 "left": (g.size().width - divWidth - 2) + "px",
73 "background": "white",
74 "lineHeight": "normal",
75 "textAlign": "left",
76 "overflow": "hidden"};
77
78 // TODO(danvk): get rid of labelsDivStyles? CSS is better.
79 Dygraph.update(messagestyle, g.getOption('labelsDivStyles'));
80 div = document.createElement("div");
81 div.className = "dygraph-legend";
82 for (var name in messagestyle) {
83 if (!messagestyle.hasOwnProperty(name)) continue;
84
85 try {
86 div.style[name] = messagestyle[name];
87 } catch (e) {
88 console.warn("You are using unsupported css properties for your " +
89 "browser in labelsDivStyles");
90 }
91 }
92
93 // TODO(danvk): come up with a cleaner way to expose this.
94 g.graphDiv.appendChild(div);
95 this.is_generated_div_ = true;
96 }
97
98 this.legend_div_ = div;
99 this.one_em_width_ = 10; // just a guess, will be updated.
100
101 return {
102 select: this.select,
103 deselect: this.deselect,
104 // TODO(danvk): rethink the name "predraw" before we commit to it in any API.
105 predraw: this.predraw,
106 didDrawChart: this.didDrawChart
107 };
108 };
109
110 // Needed for dashed lines.
111 var calculateEmWidthInDiv = function(div) {
112 var sizeSpan = document.createElement('span');
113 sizeSpan.setAttribute('style', 'margin: 0; padding: 0 0 0 1em; border: 0;');
114 div.appendChild(sizeSpan);
115 var oneEmWidth=sizeSpan.offsetWidth;
116 div.removeChild(sizeSpan);
117 return oneEmWidth;
118 };
119
120 var escapeHTML = function(str) {
121 return str.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
122 };
123
124 legend.prototype.select = function(e) {
125 var xValue = e.selectedX;
126 var points = e.selectedPoints;
127
128 if (e.dygraph.getOption('legend') === 'follow') {
129 // create floating legend div
130 var area = e.dygraph.plotter_.area;
131 var labelsDivWidth = e.dygraph.getOption('labelsDivWidth');
132 var yAxisLabelWidth = e.dygraph.getOptionForAxis('axisLabelWidth', 'y');
133 // determine floating [left, top] coordinates of the legend div
134 // within the plotter_ area
135 // offset 20 px to the right and down from the first selection point
136 // 20 px is guess based on mouse cursor size
137 var leftLegend = points[0].x * area.w + 20;
138 var topLegend = points[0].y * area.h - 20;
139
140 // if legend floats to end of the window area, it flips to the other
141 // side of the selection point
142 if ((leftLegend + labelsDivWidth + 1) > (window.scrollX + window.innerWidth)) {
143 leftLegend = leftLegend - 2 * 20 - labelsDivWidth - (yAxisLabelWidth - area.x);
144 }
145
146 e.dygraph.graphDiv.appendChild(this.legend_div_);
147 this.legend_div_.style.left = yAxisLabelWidth + leftLegend + "px";
148 this.legend_div_.style.top = topLegend + "px";
149 this.legend_div_.style.display = '';
150 }
151
152 var html = legend.generateLegendHTML(e.dygraph, xValue, points, this.one_em_width_);
153 this.legend_div_.innerHTML = html;
154 };
155
156 legend.prototype.deselect = function(e) {
157
158 if (e.dygraph.getOption("legend") === "follow") {
159 this.legend_div_.style.display = "none";
160 }
161
162 // Have to do this every time, since styles might have changed.
163 var oneEmWidth = calculateEmWidthInDiv(this.legend_div_);
164 this.one_em_width_ = oneEmWidth;
165
166 var html = legend.generateLegendHTML(e.dygraph, undefined, undefined, oneEmWidth);
167 this.legend_div_.innerHTML = html;
168 };
169
170 legend.prototype.didDrawChart = function(e) {
171 this.deselect(e);
172 };
173
174 // Right edge should be flush with the right edge of the charting area (which
175 // may not be the same as the right edge of the div, if we have two y-axes.
176 // TODO(danvk): is any of this really necessary? Could just set "right" in "activate".
177 /**
178 * Position the labels div so that:
179 * - its right edge is flush with the right edge of the charting area
180 * - its top edge is flush with the top edge of the charting area
181 * @private
182 */
183 legend.prototype.predraw = function(e) {
184 // Don't touch a user-specified labelsDiv.
185 if (!this.is_generated_div_) return;
186
187 // TODO(danvk): only use real APIs for this.
188 e.dygraph.graphDiv.appendChild(this.legend_div_);
189 var area = e.dygraph.plotter_.area;
190 var labelsDivWidth = e.dygraph.getOption("labelsDivWidth");
191 this.legend_div_.style.left = area.x + area.w - labelsDivWidth - 1 + "px";
192 this.legend_div_.style.top = area.y + "px";
193 this.legend_div_.style.width = labelsDivWidth + "px";
194 };
195
196 /**
197 * Called when dygraph.destroy() is called.
198 * You should null out any references and detach any DOM elements.
199 */
200 legend.prototype.destroy = function() {
201 this.legend_div_ = null;
202 };
203
204 /**
205 * @private
206 * Generates HTML for the legend which is displayed when hovering over the
207 * chart. If no selected points are specified, a default legend is returned
208 * (this may just be the empty string).
209 * @param { Number } [x] The x-value of the selected points.
210 * @param { [Object] } [sel_points] List of selected points for the given
211 * x-value. Should have properties like 'name', 'yval' and 'canvasy'.
212 * @param { Number } [oneEmWidth] The pixel width for 1em in the legend. Only
213 * relevant when displaying a legend with no selection (i.e. {legend:
214 * 'always'}) and with dashed lines.
215 */
216 legend.generateLegendHTML = function(g, x, sel_points, oneEmWidth) {
217 // TODO(danvk): deprecate this option in place of {legend: 'never'}
218 if (g.getOption('showLabelsOnHighlight') !== true) return '';
219
220 // If no points are selected, we display a default legend. Traditionally,
221 // this has been blank. But a better default would be a conventional legend,
222 // which provides essential information for a non-interactive chart.
223 var html, sepLines, i, dash, strokePattern;
224 var labels = g.getLabels();
225
226 if (typeof(x) === 'undefined') {
227 if (g.getOption('legend') != 'always') {
228 return '';
229 }
230
231 sepLines = g.getOption('labelsSeparateLines');
232 html = '';
233 for (i = 1; i < labels.length; i++) {
234 var series = g.getPropertiesForSeries(labels[i]);
235 if (!series.visible) continue;
236
237 if (html !== '') html += (sepLines ? '<br/>' : ' ');
238 strokePattern = g.getOption("strokePattern", labels[i]);
239 dash = generateLegendDashHTML(strokePattern, series.color, oneEmWidth);
240 html += "<span style='font-weight: bold; color: " + series.color + ";'>" +
241 dash + " " + escapeHTML(labels[i]) + "</span>";
242 }
243 return html;
244 }
245
246 // TODO(danvk): remove this use of a private API
247 var xOptView = g.optionsViewForAxis_('x');
248 var xvf = xOptView('valueFormatter');
249 html = xvf(x, xOptView, labels[0], g);
250 if (html !== '') {
251 html += ':';
252 }
253
254 var yOptViews = [];
255 var num_axes = g.numAxes();
256 for (i = 0; i < num_axes; i++) {
257 // TODO(danvk): remove this use of a private API
258 yOptViews[i] = g.optionsViewForAxis_('y' + (i ? 1 + i : ''));
259 }
260 var showZeros = g.getOption("labelsShowZeroValues");
261 sepLines = g.getOption("labelsSeparateLines");
262 var highlightSeries = g.getHighlightSeries();
263 for (i = 0; i < sel_points.length; i++) {
264 var pt = sel_points[i];
265 if (pt.yval === 0 && !showZeros) continue;
266 if (!Dygraph.isOK(pt.canvasy)) continue;
267 if (sepLines) html += "<br/>";
268
269 var series = g.getPropertiesForSeries(pt.name);
270 var yOptView = yOptViews[series.axis - 1];
271 var fmtFunc = yOptView('valueFormatter');
272 var yval = fmtFunc(pt.yval, yOptView, pt.name, g);
273
274 var cls = (pt.name == highlightSeries) ? " class='highlight'" : "";
275
276 // TODO(danvk): use a template string here and make it an attribute.
277 html += "<span" + cls + ">" + " <b><span style='color: " + series.color + ";'>" +
278 escapeHTML(pt.name) + "</span></b>:&#160;" + yval + "</span>";
279 }
280 return html;
281 };
282
283
284 /**
285 * Generates html for the "dash" displayed on the legend when using "legend: always".
286 * In particular, this works for dashed lines with any stroke pattern. It will
287 * try to scale the pattern to fit in 1em width. Or if small enough repeat the
288 * pattern for 1em width.
289 *
290 * @param strokePattern The pattern
291 * @param color The color of the series.
292 * @param oneEmWidth The width in pixels of 1em in the legend.
293 * @private
294 */
295 generateLegendDashHTML = function(strokePattern, color, oneEmWidth) {
296 // IE 7,8 fail at these divs, so they get boring legend, have not tested 9.
297 var isIE = (/MSIE/.test(navigator.userAgent) && !window.opera);
298 if (isIE) return "&mdash;";
299
300 // Easy, common case: a solid line
301 if (!strokePattern || strokePattern.length <= 1) {
302 return "<div style=\"display: inline-block; position: relative; " +
303 "bottom: .5ex; padding-left: 1em; height: 1px; " +
304 "border-bottom: 2px solid " + color + ";\"></div>";
305 }
306
307 var i, j, paddingLeft, marginRight;
308 var strokePixelLength = 0, segmentLoop = 0;
309 var normalizedPattern = [];
310 var loop;
311
312 // Compute the length of the pixels including the first segment twice,
313 // since we repeat it.
314 for (i = 0; i <= strokePattern.length; i++) {
315 strokePixelLength += strokePattern[i%strokePattern.length];
316 }
317
318 // See if we can loop the pattern by itself at least twice.
319 loop = Math.floor(oneEmWidth/(strokePixelLength-strokePattern[0]));
320 if (loop > 1) {
321 // This pattern fits at least two times, no scaling just convert to em;
322 for (i = 0; i < strokePattern.length; i++) {
323 normalizedPattern[i] = strokePattern[i]/oneEmWidth;
324 }
325 // Since we are repeating the pattern, we don't worry about repeating the
326 // first segment in one draw.
327 segmentLoop = normalizedPattern.length;
328 } else {
329 // If the pattern doesn't fit in the legend we scale it to fit.
330 loop = 1;
331 for (i = 0; i < strokePattern.length; i++) {
332 normalizedPattern[i] = strokePattern[i]/strokePixelLength;
333 }
334 // For the scaled patterns we do redraw the first segment.
335 segmentLoop = normalizedPattern.length+1;
336 }
337
338 // Now make the pattern.
339 var dash = "";
340 for (j = 0; j < loop; j++) {
341 for (i = 0; i < segmentLoop; i+=2) {
342 // The padding is the drawn segment.
343 paddingLeft = normalizedPattern[i%normalizedPattern.length];
344 if (i < strokePattern.length) {
345 // The margin is the space segment.
346 marginRight = normalizedPattern[(i+1)%normalizedPattern.length];
347 } else {
348 // The repeated first segment has no right margin.
349 marginRight = 0;
350 }
351 dash += "<div style=\"display: inline-block; position: relative; " +
352 "bottom: .5ex; margin-right: " + marginRight + "em; padding-left: " +
353 paddingLeft + "em; height: 1px; border-bottom: 2px solid " + color +
354 ";\"></div>";
355 }
356 }
357 return dash;
358 };
359
360
361 return legend;
362 })();