Commit | Line | Data |
---|---|---|
14403441 DV |
1 | <!--#include virtual="header.html" --> |
2 | ||
3 | <style type="text/css"> | |
4 | code { white-space: pre; } | |
5 | pre { white-space: pre; } | |
6 | .annotation { | |
7 | font-size: 12px !important; | |
8 | } | |
9 | </style> | |
10 | ||
11 | <h2>dygraphs Annotations</h2> | |
12 | ||
13 | <p>dygraphs lets you add annotations (markers) to individual points on your | |
14 | chart. These markers have a short bit of text or an icon that's displayed | |
15 | over the chart, plus a longer description that appears when you hover over | |
16 | them.</p> | |
17 | ||
18 | <h3>Demo: Dow Jones Industrial Average</h3> | |
19 | <div id="dow_chart" style="width: 800px; height: 250px;"></div> | |
20 | <script type="text/javascript"> | |
21 | // From http://www.econstats.com/eqty/eq_d_mi_3.csv | |
22 | stockchart = new Dygraph( | |
23 | document.getElementById('dow_chart'), | |
24 | "dow.txt", | |
25 | { | |
26 | showRoller: true, | |
27 | customBars: true, | |
28 | labelsKMB: true, | |
5bcc58b4 | 29 | labelsDivWidth: 300 |
14403441 DV |
30 | } |
31 | ); | |
5bcc58b4 DV |
32 | |
33 | stockchart.ready(function(g) { | |
34 | g.setAnnotations( [ | |
35 | { | |
36 | series: "Real", | |
37 | x: "1929-08-15", | |
38 | shortText: "A", | |
39 | text: "1929 Stock Market Peak", | |
40 | cssClass: 'annotation' | |
41 | }, | |
42 | { | |
43 | series: "Nominal", | |
44 | x: "1987-08-15", | |
45 | shortText: "B", | |
46 | text: "1987 Crash", | |
47 | cssClass: 'annotation' | |
48 | }, | |
49 | { | |
50 | series: "Nominal", | |
51 | x: "1999-12-15", | |
52 | shortText: "C", | |
53 | text: "1999 (.com) Peak", | |
54 | cssClass: 'annotation' | |
55 | }, | |
56 | { | |
57 | series: "Nominal", | |
58 | x: "2007-10-15", | |
59 | shortText: "D", | |
60 | text: "All-Time Market Peak", | |
61 | cssClass: 'annotation' | |
62 | } | |
63 | ] ); | |
64 | }); | |
14403441 DV |
65 | </script> |
66 | ||
67 | <h3>Adding Annotations</h3> | |
68 | ||
69 | <p>There are two methods which are used to add, remove and modify annotations:</p> | |
70 | ||
71 | <table class="thinborder"> | |
72 | <tr> | |
73 | <td><code>setAnnotations(array)</code></td> | |
74 | <td>Set the list of annotations currently displayed. This overwrites | |
75 | existing annotations and redraws the dygraph.</td> | |
76 | </tr> | |
77 | <tr> | |
78 | <td><code>annotations</code></td> | |
79 | <td>Returns an array of the currently-displayed annotations.</td> | |
80 | </tr> | |
81 | </table> | |
82 | ||
83 | <p>Calling <code>dygraph.setAnnotations(dygraph.annotations())</code> is a | |
84 | no-op: it simply causes the chart to refresh.</p> | |
85 | ||
86 | <p>Let's say we have a simple chart and wish to add an annotation. Here's how:</p> | |
87 | ||
88 | <div class="example" style="clear:both;"> | |
89 | <div class="codeblock" style="float:left;width:400px;"> | |
90 | <h3 style="text-align:center">HTML</h3> | |
534f1a05 DV |
91 | <pre> |
92 | <script type="text/javascript"> | |
93 | g = new Dygraph( | |
94 | document.getElementById("graphdiv"), | |
95 | "Date,Temperature\n" + | |
96 | "2008-05-07,75\n" + | |
97 | "2008-05-08,70\n" + | |
98 | "2008-05-09,80\n" | |
99 | ); | |
100 | ||
101 | g.setAnnotations([ | |
102 | { | |
103 | series: "Temperature", | |
104 | x: "2008-05-08", | |
105 | shortText: "L", | |
106 | text: "Coldest Day" | |
107 | } | |
108 | ]); | |
109 | </script> | |
110 | </pre> | |
14403441 DV |
111 | </div> |
112 | ||
113 | <div class="codeoutput" style="float:left;"> | |
114 | <h3 style="text-align:center">OUTPUT</h3> | |
115 | <div id="graphdiv" style="width: 350px; height: 250px;"></div> | |
116 | <script type="text/javascript"> | |
117 | g = new Dygraph( | |
118 | ||
119 | // containing div | |
120 | document.getElementById("graphdiv"), | |
121 | ||
122 | // CSV or path to a CSV file. | |
123 | "Date,Temperature\n" + | |
124 | "2008-05-07,75\n" + | |
125 | "2008-05-08,70\n" + | |
126 | "2008-05-09,80\n" | |
127 | ); | |
128 | g.setAnnotations([ | |
129 | { | |
130 | series: "Temperature", | |
131 | x: "2008-05-08", | |
132 | shortText: "L", | |
133 | text: "Coldest Day" | |
534f1a05 | 134 | } |
14403441 DV |
135 | ]); |
136 | </script> | |
137 | </div> | |
138 | </div> | |
139 | ||
140 | <p style="clear:both">Annotations are JavaScript dictionaries. The <code>series</code> and <code>x</code> fields are required: they indicate which point the annotation should be attached to. If specified, <code>shortText</code> will appear on the annotation "flag". If you don't specify <code>shortText</code>, you can specify <code>icon</code> instead to display a small picture. The <code>text</code> parameter specifies hovertext. If you highlight the annotation and leave the mouse still, it will appear.</p> | |
141 | ||
142 | <p>If you are using <a href="http://dygraphs.com/data.html#array">native format</a>, you need to pass in a numeric value for the <code>x</code> field. For a numeric x-axis, simply pass in the x-value of the data point on which you wish to attach the annotation. For a date axis, pass in <code>Date.parse('YYYY/MM/DD')</code>. This returns milliseconds since epoch for the date.</p> | |
143 | ||
144 | <h3>Modifying Annotations</h3> | |
145 | <p>To remove or modify existing annotations, call the | |
146 | <code>annotations</code> method to get an array of annotations. Modify that | |
147 | array, then pass it back in to <code>setAnnotations</code>. For example, this | |
148 | code deletes the second annotation and changes the series to which the first | |
149 | is attached:</p> | |
150 | ||
151 | <pre> | |
152 | var annotations = g.annotations(); | |
153 | annotations.splice(1,1); // remove the second annotation | |
154 | annotations[0].series = "Series 2"; | |
155 | g.setAnnotations(annotations); // causes a redraw | |
156 | </pre> | |
534f1a05 | 157 | |
14403441 DV |
158 | <p>For a more real-life example, see the <a |
159 | href="tests/annotation.html">annotations demo</a></p> | |
160 | ||
5bcc58b4 DV |
161 | <h3>Annotations and Data Sources</h3> |
162 | <p>When you pass a URL as the data source to dygraphs, it must issue a request | |
163 | for the data before drawing the chart. This means that the chart data is not yet | |
164 | available immediately after you call <code>new Dygraph</code> and so the call to | |
165 | <code>g.setAnnotations</code> will fail. The best way around this is to use the | |
166 | <code>ready()</code> method:</p> | |
167 | ||
168 | <pre>g = new Dygraph(div, "path/to/data.csv"); | |
169 | g.ready(function() { | |
170 | // This is called when data.csv comes back and the chart draws. | |
171 | g.setAnnotations([ | |
172 | … | |
173 | ]); | |
174 | }); | |
175 | </pre> | |
176 | ||
14403441 DV |
177 | <h3>Annotations property reference</h3> |
178 | <p>These properties can all be set in the dictionary for an annotation. The use of each one is demonstrated on the <a href="tests/annotation.html">annotations demo</a> page.</p> | |
179 | ||
180 | <table class="thinborder"> | |
181 | <tr> <td><b>Property</b></td><td><b>Description</b></td> </tr> | |
182 | <tr><td><code>series</code></td> <td><i>Required</i> The name of the series to which the annotated point belongs.</td></tr> | |
183 | <tr><td><code>x</code></td><td><i>Required</i> The x value of the point. This should be the same as the value you specified in your CSV file, e.g. "2010-09-13".</td></tr> | |
184 | <tr><td><code>shortText</code></td><td>Text that will appear on the annotation's flag.</td></tr> | |
185 | <tr><td><code>text</code></td><td>A longer description of the annotation which will appear when the user hovers over it.</td></tr> | |
186 | <tr><td><code>icon</code></td><td>Specify in place of <code>shortText</code> to mark the annotation with an image rather than text. If you specify this, you must specify <code>width</code> and <code>height</code>.</td></tr> | |
187 | <tr><td><code>width</code></td><td>Width (in pixels) of the annotation flag or icon.</td></tr> | |
188 | <tr><td><code>height</code></td><td>Height (in pixels) of the annotation flag or icon.</td></tr> | |
189 | <tr><td><code>cssClass</code></td><td>CSS class to use for styling the annotation.</td></tr> | |
190 | <tr><td><code>tickHeight</code></td><td>Height of the tick mark (in pixels) connecting the point to its flag or icon.</td></tr> | |
191 | <tr><td><code>attachAtBottom</code></td><td>If true, attach annotations to the x-axis, rather than to actual points.</td></tr> | |
192 | <tr><td><code>clickHandler</code></td> <td>See Handlers, below</td></tr> | |
193 | <tr><td><code>mouseOverHandler</code></td><td>See Handlers, below</td></tr> | |
194 | <tr><td><code>mouseOutHandler</code></td> <td>See Handlers, below</td></tr> | |
195 | <tr><td><code>dblClickHandler</code></td> <td>See Handlers, below</td></tr> | |
196 | </table> | |
197 | ||
198 | <h3>Annotation event handlers</h3> | |
199 | ||
200 | <p>dygraphs lets you attach event handlers to your annotations. These can be | |
201 | specified globally (for all annotations) or on a per-annotation basis:</p> | |
202 | ||
203 | <table class="thinborder"> | |
204 | <tr><td><b>Per-point field</b></td><td><b>Global option</b></td></tr> | |
205 | <tr><td><code>clickHandler</code></td> <td><code>annotationClickHandler</code></td></tr> | |
206 | <tr><td><code>mouseOverHandler</code></td><td><code>annotationMouseOverHandler</code></td></tr> | |
207 | <tr><td><code>mouseOutHandler</code></td> <td><code>annotationMouseOutHandler</code></td></tr> | |
208 | <tr><td><code>dblClickHandler</code></td> <td><code>annotationDblClickHandler</code></td></tr> | |
209 | </table> | |
210 | ||
211 | <p>These event handlers all take the same parameters:</p> | |
212 | ||
213 | <pre>g.updateOptions( { | |
214 | annotationClickHandler: function(annotation, point, dygraph, event) { | |
215 | // ... access/modify annotation.series, annotation.x, ... | |
216 | } | |
217 | }); </pre> | |
534f1a05 | 218 | |
14403441 DV |
219 | <p>Again, check out the <a href="tests/annotation.html">annotations demo</a> |
220 | for concrete examples of usage of all these handlers.</p> | |
d731e964 | 221 | |
14403441 | 222 | <!--#include virtual="footer.html" --> |