fractions
[dygraphs.git] / docs / annotations.html
1 <html>
2 <head>
3 <title>dygraphs annotations</title>
4 <style type="text/css">
5 code { white-space: pre; }
6 pre { white-space: pre; }
7 body { max-width: 800px; }
8 </style>
9 <!--[if IE]>
10 <script type="text/javascript" src="excanvas.js"></script>
11 <![endif]-->
12 <script type="text/javascript" src="dygraph-combined.js"></script>
13 <link rel="stylesheet" href="style.css">
14 </head>
15 <body>
16 <h2>dygraphs Annotations</h2>
17
18 <p>dygraphs lets you add annotations (markers) to individual points on your
19 chart. These markers have a short bit of text or an icon that's displayed
20 over the chart, plus a longer description that appears when you hover over
21 them.</p>
22
23 <h3>Demo: Dow Jones Industrial Average</h3>
24 <div id="dow_chart" style="width: 800px; height: 250px;"></div>
25 <script type="text/javascript">
26 // From http://www.econstats.com/eqty/eq_d_mi_3.csv
27 stockchart = new Dygraph(
28 document.getElementById('dow_chart'),
29 "dow.txt",
30 {
31 showRoller: true,
32 customBars: true,
33 labelsKMB: true,
34 labelsDivWidth: 300,
35 drawCallback: function(g, is_initial) {
36 if (!is_initial) return;
37
38 g.setAnnotations( [
39 {
40 series: "Real",
41 x: "1929-08-15",
42 shortText: "A",
43 text: "1929 Stock Market Peak"
44 },
45 {
46 series: "Nominal",
47 x: "1987-08-15",
48 shortText: "B",
49 text: "1987 Crash"
50 },
51 {
52 series: "Nominal",
53 x: "1999-12-15",
54 shortText: "C",
55 text: "1999 (.com) Peak"
56 },
57 {
58 series: "Nominal",
59 x: "2007-10-15",
60 shortText: "D",
61 text: "All-Time Market Peak"
62 }
63 ] );
64 }
65 }
66 );
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
86 no-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>
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
103 g.setAnnotations([
104 {
105 series: &quot;Temperature&quot;,
106 x: &quot;2008-05-08&quot;,
107 shortText: &quot;L&quot;,
108 text: &quot;Coldest Day&quot;
109 }
110 ]);
111 &lt;/script&gt;
112 </pre>
113 </div>
114 <div class="codeoutput" style="float:left;">
115 <h3 style="text-align:center">OUTPUT</h3>
116 <div id="graphdiv" style="width: 350px; height: 250px;"></div>
117 <script type="text/javascript">
118 g = new Dygraph(
119
120 // containing div
121 document.getElementById("graphdiv"),
122
123 // CSV or path to a CSV file.
124 "Date,Temperature\n" +
125 "2008-05-07,75\n" +
126 "2008-05-08,70\n" +
127 "2008-05-09,80\n"
128 );
129 g.setAnnotations([
130 {
131 series: "Temperature",
132 x: "2008-05-08",
133 shortText: "L",
134 text: "Coldest Day"
135 }
136 ]);
137 </script>
138 </div>
139 </div>
140
141 <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
143 <h3>Modifying Annotations</h3>
144 <p>To remove or modify existing annotations, call the
145 <code>annotations</code> method to get an array of annotations. Modify that
146 array, then pass it back in to <code>setAnnotations</code>. For example, this
147 code deletes the second annotation and changes the series to which the first
148 is attached:</p>
149
150 <pre>
151 var annotations = g.annotations();
152 annotations.splice(1,1); // remove the second annotation
153 annotations[0].series = "Series 2";
154 g.setAnnotations(annotations); // causes a redraw
155 </pre>
156
157 <p>For a more real-life example, see the <a
158 href="tests/annotation.html">annotations demo</a></p>
159
160 <h3>Annotations property reference</h3>
161 <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>
162
163 <table class="thinborder">
164 <tr> <td><b>Property</b></td><td><b>Description</b></td> </tr>
165 <tr><td><code>series</code></td> <td><i>Required</i> The name of the series to which the annotated point belongs.</td></tr>
166 <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>
167 <tr><td><code>shortText</code></td><td>Text that will appear on the annotation's flag.</td></tr>
168 <tr><td><code>text</code></td><td>A longer description of the annotation which will appear when the user hovers over it.</td></tr>
169 <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>
170 <tr><td><code>width</code></td><td>Width (in pixels) of the annotation flag or icon.</td></tr>
171 <tr><td><code>height</code></td><td>Height (in pixels) of the annotation flag or icon.</td></tr>
172 <tr><td><code>cssClass</code></td><td>CSS class to use for styling the annotation.</td></tr>
173 <tr><td><code>tickHeight</code></td><td>Height of the tick mark (in pixels) connecting the point to its flag or icon.</td></tr>
174 <tr><td><code>attachAtBottom</code></td><td>If true, attach annotations to the x-axis, rather than to actual points.</td></tr>
175 <tr><td><code>clickHandler</code></td> <td>See Handlers, below</td></tr>
176 <tr><td><code>mouseOverHandler</code></td><td>See Handlers, below</td></tr>
177 <tr><td><code>mouseOutHandler</code></td> <td>See Handlers, below</td></tr>
178 <tr><td><code>dblClickHandler</code></td> <td>See Handlers, below</td></tr>
179 </table>
180
181 <h3>Annotation event handlers</h3>
182
183 <p>dygraphs lets you attach event handlers to your annotations. These can be
184 specified globally (for all annotations) or on a per-annotation basis:</p>
185
186 <table class="thinborder">
187 <tr><td><b>Per-point field</b></td><td><b>Global option</b></td></tr>
188 <tr><td><code>clickHandler</code></td> <td><code>annotationClickHandler</code></td></tr>
189 <tr><td><code>mouseOverHandler</code></td><td><code>annotationMouseOverHandler</code></td></tr>
190 <tr><td><code>mouseOutHandler</code></td> <td><code>annotationMouseOutHandler</code></td></tr>
191 <tr><td><code>dblClickHandler</code></td> <td><code>annotationDblClickHandler</code></td></tr>
192 </table>
193
194 <p>These event handlers all take the same parameters:</p>
195
196 <pre>
197 g.updateOptions( {
198 annotationClickHandler: function(annotation, point, dygraph, event) {
199 // ... access/modify annotation.series, annotation.x, ...
200 }
201 });
202 </pre>
203
204 <p>Again, check out the <a href="tests/annotation.html">annotations demo</a>
205 for concrete examples of usage of all these handlers.</p>
206
207 </body>
208 </html>