1 <!--#include
virtual=
"header.html" --
>
3 <style type=
"text/css">
4 code { white-space: pre; }
5 pre { white-space: pre; }
7 font-size:
12px !important;
14 <h2>dygraphs Annotations
</h2>
16 <p>dygraphs lets you add annotations (markers) to individual points on your
17 chart. These markers have a short bit of text or an icon that's displayed
18 over the chart, plus a longer description that appears when you hover over
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'),
35 stockchart.ready(function(g) {
41 text:
"1929 Stock Market Peak",
42 cssClass: 'annotation'
49 cssClass: 'annotation'
55 text:
"1999 (.com) Peak",
56 cssClass: 'annotation'
62 text:
"All-Time Market Peak",
63 cssClass: 'annotation'
69 <h3>Adding Annotations
</h3>
71 <p>There are two methods which are used to add, remove and modify annotations:
</p>
73 <table class=
"thinborder">
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>
80 <td><code>annotations
</code></td>
81 <td>Returns an array of the currently-displayed annotations.
</td>
85 <p>Calling
<code>dygraph.setAnnotations(dygraph.annotations())
</code> is a
86 no-op: it simply causes the chart to refresh.
</p>
88 <p>Let's say we have a simple chart and wish to add an annotation. Here's how:
</p>
90 <div class=
"example" style=
"clear:both;">
91 <div class=
"codeblock" style=
"float:left;width:400px;">
92 <h3 style=
"text-align:center">HTML
</h3>
94 <script type=
"text/javascript
">
96 document.getElementById(
"graphdiv
"),
97 "Date,Temperature
\n" +
98 "2008-
05-
07,
75\n" +
99 "2008-
05-
08,
70\n" +
100 "2008-
05-
09,
80\n"
106 series:
"Temperature
",
107 x:
"2008-
05-
08",
108 shortText:
"L
",
109 text:
"Coldest Day
"
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">
124 document.getElementById(
"graphdiv"),
126 // CSV or path to a CSV file.
127 "Date,Temperature\n" +
135 series:
"Temperature",
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>
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>
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
153 array, then pass it back in to
<code>setAnnotations
</code>. For example, this
154 code deletes the second annotation and changes the series to which the first
158 var annotations = g.annotations();
159 annotations.splice(
1,
1); // remove the second annotation
160 annotations[
0].series =
"Series 2";
161 g.setAnnotations(annotations); // causes a redraw
164 <p>For a more real-life example, see the
<a
165 href=
"tests/annotation.html">annotations demo
</a></p>
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
169 for the data before drawing the chart. This means that the chart data is not yet
170 available 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>
174 <pre>g = new Dygraph(div,
"path/to/data.csv");
176 // This is called when data.csv comes back and the chart draws.
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>
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>tickWidth
</code></td><td>Width of the tick mark connecting the point to its flag or icon.
</td></tr>
198 <tr><td><code>tickColor
</code></td><td>Color of the tick mark connecting the point to its flag or icon.
</td></tr>
199 <tr><td><code>attachAtBottom
</code></td><td>If true, attach annotations to the x-axis, rather than to actual points.
</td></tr>
200 <tr><td><code>clickHandler
</code></td> <td>See Handlers, below
</td></tr>
201 <tr><td><code>mouseOverHandler
</code></td><td>See Handlers, below
</td></tr>
202 <tr><td><code>mouseOutHandler
</code></td> <td>See Handlers, below
</td></tr>
203 <tr><td><code>dblClickHandler
</code></td> <td>See Handlers, below
</td></tr>
206 <h3>Annotation event handlers
</h3>
208 <p>dygraphs lets you attach event handlers to your annotations. These can be
209 specified globally (for all annotations) or on a per-annotation basis:
</p>
211 <table class=
"thinborder">
212 <tr><td><b>Per-point field
</b></td><td><b>Global option
</b></td></tr>
213 <tr><td><code>clickHandler
</code></td> <td><code>annotationClickHandler
</code></td></tr>
214 <tr><td><code>mouseOverHandler
</code></td><td><code>annotationMouseOverHandler
</code></td></tr>
215 <tr><td><code>mouseOutHandler
</code></td> <td><code>annotationMouseOutHandler
</code></td></tr>
216 <tr><td><code>dblClickHandler
</code></td> <td><code>annotationDblClickHandler
</code></td></tr>
219 <p>These event handlers all take the same parameters:
</p>
221 <pre>g.updateOptions( {
222 annotationClickHandler: function(annotation, point, dygraph, event) {
223 // ... access/modify annotation.series, annotation.x, ...
227 <p>Again, check out the
<a href=
"tests/annotation.html">annotations demo
</a>
228 for concrete examples of usage of all these handlers.
</p>
230 <!--#include
virtual=
"footer.html" --
>