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;
11 <h2>dygraphs Annotations
</h2>
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
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'),
33 stockchart.ready(function(g) {
39 text:
"1929 Stock Market Peak",
40 cssClass: 'annotation'
47 cssClass: 'annotation'
53 text:
"1999 (.com) Peak",
54 cssClass: 'annotation'
60 text:
"All-Time Market Peak",
61 cssClass: 'annotation'
67 <h3>Adding Annotations
</h3>
69 <p>There are two methods which are used to add, remove and modify annotations:
</p>
71 <table class=
"thinborder">
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>
78 <td><code>annotations
</code></td>
79 <td>Returns an array of the currently-displayed annotations.
</td>
83 <p>Calling
<code>dygraph.setAnnotations(dygraph.annotations())
</code> is a
84 no-op: it simply causes the chart to refresh.
</p>
86 <p>Let's say we have a simple chart and wish to add an annotation. Here's how:
</p>
88 <div class=
"example" style=
"clear:both;">
89 <div class=
"codeblock" style=
"float:left;width:400px;">
90 <h3 style=
"text-align:center">HTML
</h3>
92 <script type=
"text/javascript
">
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"
103 series:
"Temperature
",
104 x:
"2008-
05-
08",
105 shortText:
"L
",
106 text:
"Coldest Day
"
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">
120 document.getElementById(
"graphdiv"),
122 // CSV or path to a CSV file.
123 "Date,Temperature\n" +
130 series:
"Temperature",
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>
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>
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
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
158 <p>For a more real-life example, see the
<a
159 href=
"tests/annotation.html">annotations demo
</a></p>
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>
168 <pre>g = new Dygraph(div,
"path/to/data.csv");
170 // This is called when data.csv comes back and the chart draws.
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>
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>
198 <h3>Annotation event handlers
</h3>
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>
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>
211 <p>These event handlers all take the same parameters:
</p>
213 <pre>g.updateOptions( {
214 annotationClickHandler: function(annotation, point, dygraph, event) {
215 // ... access/modify annotation.series, annotation.x, ...
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>
222 <!--#include
virtual=
"footer.html" --
>