projects / dygraphs.git / blame
| Commit | Line | Data |
|---|---|---|
| 53e5cec3 | 1 | <!DOCTYPE html> |
| 534f1a05 DV |
2 | <html> |
| 3 | <head> | |
| 4 | <title>dygraphs annotations</title> | |
| 5 | <style type="text/css"> | |
| 6 | code { white-space: pre; } | |
| 7 | pre { white-space: pre; } | |
| 8 | body { max-width: 800px; } | |
| 9 | </style> | |
| 10 | <!--[if IE]> | |
| 11 | <script type="text/javascript" src="excanvas.js"></script> | |
| 12 | <![endif]--> | |
| 2a9e1bdf | 13 | <script type="text/javascript" src="dygraph-combined.js"></script> |
| 534f1a05 DV |
14 | <link rel="stylesheet" href="style.css"> |
| 15 | </head> | |
| 16 | <body> | |
| 17 | <h2>dygraphs Annotations</h2> | |
| 18 | ||
| 19 | <p>dygraphs lets you add annotations (markers) to individual points on your | |
| 20 | chart. These markers have a short bit of text or an icon that's displayed | |
| 21 | over the chart, plus a longer description that appears when you hover over | |
| 22 | them.</p> | |
| 23 | ||
| 24 | <h3>Demo: Dow Jones Industrial Average</h3> | |
| 9f0e1fe1 | 25 | <div id="dow_chart" style="width: 800px; height: 250px;"></div> |
| 534f1a05 DV |
26 | <script type="text/javascript"> |
| 27 | // From http://www.econstats.com/eqty/eq_d_mi_3.csv | |
| 28 | stockchart = new Dygraph( | |
| 29 | document.getElementById('dow_chart'), | |
| 30 | "dow.txt", | |
| 31 | { | |
| 32 | showRoller: true, | |
| 33 | customBars: true, | |
| 34 | labelsKMB: true, | |
| 35 | labelsDivWidth: 300, | |
| 36 | drawCallback: function(g, is_initial) { | |
| 37 | if (!is_initial) return; | |
| 38 | ||
| 39 | g.setAnnotations( [ | |
| 40 | { | |
| 41 | series: "Real", | |
| 42 | x: "1929-08-15", | |
| 43 | shortText: "A", | |
| 44 | text: "1929 Stock Market Peak" | |
| 45 | }, | |
| 46 | { | |
| 47 | series: "Nominal", | |
| 48 | x: "1987-08-15", | |
| 49 | shortText: "B", | |
| 50 | text: "1987 Crash" | |
| 51 | }, | |
| 52 | { | |
| 53 | series: "Nominal", | |
| 54 | x: "1999-12-15", | |
| 55 | shortText: "C", | |
| 56 | text: "1999 (.com) Peak" | |
| 57 | }, | |
| 58 | { | |
| 59 | series: "Nominal", | |
| 60 | x: "2007-10-15", | |
| 61 | shortText: "D", | |
| 62 | text: "All-Time Market Peak" | |
| 63 | } | |
| 64 | ] ); | |
| 65 | } | |
| 66 | } | |
| 67 | ); | |
| 68 | </script> | |
| 69 | ||
| 70 | <h3>Adding Annotations</h3> | |
| 71 | ||
| 72 | <p>There are two methods which are used to add, remove and modify annotations:</p> | |
| 73 | ||
| 74 | <table class="thinborder"> | |
| 75 | <tr> | |
| 76 | <td><code>setAnnotations(array)</code></td> | |
| 77 | <td>Set the list of annotations currently displayed. This overwrites | |
| 78 | existing annotations and redraws the dygraph.</td> | |
| 79 | </tr> | |
| 80 | <tr> | |
| 81 | <td><code>annotations</code></td> | |
| 82 | <td>Returns an array of the currently-displayed annotations.</td> | |
| 83 | </tr> | |
| 84 | </table> | |
| 85 | ||
| 86 | <p>Calling <code>dygraph.setAnnotations(dygraph.annotations())</code> is a | |
| 87 | no-op: it simply causes the chart to refresh.</p> | |
| 88 | ||
| 89 | <p>Let's say we have a simple chart and wish to add an annotation. Here's how:</p> | |
| 90 | ||
| 91 | <div class="example" style="clear:both;"> | |
| 92 | <div class="codeblock" style="float:left;width:400px;"> | |
| 93 | <h3 style="text-align:center">HTML</h3> | |
| 94 | <pre> | |
| 95 | <script type="text/javascript"> | |
| 96 | g = new Dygraph( | |
| 97 | document.getElementById("graphdiv"), | |
| 98 | "Date,Temperature\n" + | |
| 99 | "2008-05-07,75\n" + | |
| 100 | "2008-05-08,70\n" + | |
| 101 | "2008-05-09,80\n" | |
| 102 | ); | |
| 103 | ||
| 104 | g.setAnnotations([ | |
| 105 | { | |
| 106 | series: "Temperature", | |
| 107 | x: "2008-05-08", | |
| 108 | shortText: "L", | |
| 109 | text: "Coldest Day" | |
| 110 | } | |
| 111 | ]); | |
| 112 | </script> | |
| 113 | </pre> | |
| 114 | </div> | |
| 115 | <div class="codeoutput" style="float:left;"> | |
| 116 | <h3 style="text-align:center">OUTPUT</h3> | |
| 117 | <div id="graphdiv" style="width: 350px; height: 250px;"></div> | |
| 118 | <script type="text/javascript"> | |
| 119 | g = new Dygraph( | |
| 120 | ||
| 121 | // containing div | |
| 122 | document.getElementById("graphdiv"), | |
| 123 | ||
| 124 | // CSV or path to a CSV file. | |
| 125 | "Date,Temperature\n" + | |
| 126 | "2008-05-07,75\n" + | |
| 127 | "2008-05-08,70\n" + | |
| 128 | "2008-05-09,80\n" | |
| 129 | ); | |
| 130 | g.setAnnotations([ | |
| 131 | { | |
| 132 | series: "Temperature", | |
| 133 | x: "2008-05-08", | |
| 134 | shortText: "L", | |
| 135 | text: "Coldest Day" | |
| 136 | } | |
| 137 | ]); | |
| 138 | </script> | |
| 139 | </div> | |
| 140 | </div> | |
| 141 | ||
| 142 | <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> | |
| 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> | |
| 157 | ||
| 158 | <p>For a more real-life example, see the <a | |
| 159 | href="tests/annotation.html">annotations demo</a></p> | |
| 160 | ||
| 161 | <h3>Annotations property reference</h3> | |
| 162 | <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> | |
| 163 | ||
| 164 | <table class="thinborder"> | |
| 165 | <tr> <td><b>Property</b></td><td><b>Description</b></td> </tr> | |
| 166 | <tr><td><code>series</code></td> <td><i>Required</i> The name of the series to which the annotated point belongs.</td></tr> | |
| 167 | <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> | |
| 168 | <tr><td><code>shortText</code></td><td>Text that will appear on the annotation's flag.</td></tr> | |
| 169 | <tr><td><code>text</code></td><td>A longer description of the annotation which will appear when the user hovers over it.</td></tr> | |
| 170 | <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> | |
| 171 | <tr><td><code>width</code></td><td>Width (in pixels) of the annotation flag or icon.</td></tr> | |
| 172 | <tr><td><code>height</code></td><td>Height (in pixels) of the annotation flag or icon.</td></tr> | |
| 173 | <tr><td><code>cssClass</code></td><td>CSS class to use for styling the annotation.</td></tr> | |
| 174 | <tr><td><code>tickHeight</code></td><td>Height of the tick mark (in pixels) connecting the point to its flag or icon.</td></tr> | |
| 175 | <tr><td><code>attachAtBottom</code></td><td>If true, attach annotations to the x-axis, rather than to actual points.</td></tr> | |
| 176 | <tr><td><code>clickHandler</code></td> <td>See Handlers, below</td></tr> | |
| 177 | <tr><td><code>mouseOverHandler</code></td><td>See Handlers, below</td></tr> | |
| 178 | <tr><td><code>mouseOutHandler</code></td> <td>See Handlers, below</td></tr> | |
| 179 | <tr><td><code>dblClickHandler</code></td> <td>See Handlers, below</td></tr> | |
| 180 | </table> | |
| 181 | ||
| 182 | <h3>Annotation event handlers</h3> | |
| 183 | ||
| 184 | <p>dygraphs lets you attach event handlers to your annotations. These can be | |
| 185 | specified globally (for all annotations) or on a per-annotation basis:</p> | |
| 186 | ||
| 187 | <table class="thinborder"> | |
| 188 | <tr><td><b>Per-point field</b></td><td><b>Global option</b></td></tr> | |
| 189 | <tr><td><code>clickHandler</code></td> <td><code>annotationClickHandler</code></td></tr> | |
| 190 | <tr><td><code>mouseOverHandler</code></td><td><code>annotationMouseOverHandler</code></td></tr> | |
| 191 | <tr><td><code>mouseOutHandler</code></td> <td><code>annotationMouseOutHandler</code></td></tr> | |
| 192 | <tr><td><code>dblClickHandler</code></td> <td><code>annotationDblClickHandler</code></td></tr> | |
| 193 | </table> | |
| 194 | ||
| 195 | <p>These event handlers all take the same parameters:</p> | |
| 196 | ||
| 197 | <pre> | |
| 198 | g.updateOptions( { | |
| 199 | annotationClickHandler: function(annotation, point, dygraph, event) { | |
| 200 | // ... access/modify annotation.series, annotation.x, ... | |
| 201 | } | |
| 202 | }); | |
| 203 | </pre> | |
| 204 | ||
| 205 | <p>Again, check out the <a href="tests/annotation.html">annotations demo</a> | |
| 206 | for concrete examples of usage of all these handlers.</p> | |
| 207 | ||
| 208 | </body> | |
| 209 | </html> |