cleanup
[dygraphs.git] / plugins / README
1 dygraphs plugins
2 ----------------
3
4 A single dygraph is actually a collection of dygraphs plugins, each responsible
5 for some portion of the chart: the plot area, the axes, the legend, the labels,
6 etc.
7
8 This forces the dygraphs code to be more modular and encourages better APIs.
9
10 The "legend" plugin (plugins/legend.js) can be used as a template for new
11 plugins.
12
13 Here is a simplified version of it, with comments to explain the plugin
14 lifecycle and APIs:
15
16 ----------------
17
18 // (standard JavaScript library wrapper; prevents polluting global namespace)
19 Dygraph.Plugins.Legend = (function() {
20
21 // Plugin constructor. This is invoked once for every chart which uses the
22 // plugin. You can't actually access the Dygraph object at this point, so the
23 // initialization you do here shouldn't be chart-specific. (For that, use
24 // the activate() method).
25 var legend = function() {
26   this.div_ = null;
27 };
28
29 // Plugins are expected to implement this method for debugging purposes.
30 legend.toString = function() {
31   return "Legend";
32 };
33
34 // This is called once the dygraph is ready. The chart data may not be
35 // available yet, but the options specified in the constructor are.
36 // 
37 // Proper tasks to do here include:
38 // - Reading your own options
39 // - DOM manipulation
40 // - Registering event listeners
41 //
42 // "dygraph" is the Dygraph object for which this instance is being activated.
43 // "registerer" allows you to register event listeners.
44 legend.prototype.activate = function(dygraph, registerer) {
45   // Create the legend div and attach it to the chart DOM.
46   this.div_ = document.createElement("div");
47   dygraph.graphDiv.appendChild(this.div_);
48
49   // Add event listeners. These will be called whenever points are selected
50   // (i.e. you hover over them) or deselected (i.e. you mouse away from the
51   // chart). This is your only chance to register event listeners! Once this
52   // method returns, the gig is up.
53   registerer.addEventListener('select', legend.select);
54   registerer.addEventListener('deselect', legend.deselect);
55 };
56
57 // The functions called by event listeners all take a single parameter, an
58 // event object. This contains properties relevant to the particular event, but
59 // you can always assume that it has:
60 //
61 // 1. A "dygraph" parameter which is a reference to the chart on which the
62 //    event took place.
63 // 2. A "stopPropagation" method, which you can call to prevent the event from
64 //    being seen by any other plugins after you. This effectively cancels the
65 //    event.
66 // 3. A "preventDefault" method, which prevents dygraphs from performing the
67 //    default action associated with this event.
68 //
69 legend.select = function(e) {
70   // These are two of the properties specific to the "select" event object:
71   var xValue = e.selectedX;
72   var points = e.selectedPoints;
73
74   var html = xValue + ':';
75   for (var i = 0; i < points.length; i++) {
76     var point = points[i];
77     html += ' ' + point.name + ':' + point.yval;
78   }
79
80   // In an event listener, "this" refers to your plugin object.
81   this.div_.innerHTML = html;
82 };
83
84 // This clears out the legend when the user mouses away from the chart.
85 legend.deselect = function(e) {
86   this.div_.innerHTML = '';
87 };
88
89 return legend;
90 })();
91
92 ----------------
93
94 Plugin Events Reference:
95
96 - predraw
97 - clearChart
98 - drawChart
99 - select
100 - deselect
101
102 TODO(danvk): document all event properties for each event.
103
104
105 Special methods:
106 - (constructor)
107 - activate
108 - destroy
109
110
111 ----------------
112
113 Notes on plugin registration and event cascade ordering/behavior.