| | 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 | <script type="text/javascript"> |
| | 95 | g = new Dygraph( |
| | 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" |
| | 101 | ); |
| | 102 | |
| | 103 | g.setAnnotations([ |
| | 104 | { |
| | 105 | series: "Temperature", |
| | 106 | x: "2008-05-08", |
| | 107 | shortText: "L", |
| | 108 | text: "Coldest Day" |
| | 109 | } |
| | 110 | ]); |
| | 111 | </script> |
| | 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> |
projects / dygraphs.git / blame_incremental