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