docs/annotations.html

   1 <!--#include virtual="header.html" -->
   2
   3 <style type="text/css">
   4   code { white-space: pre; }
   5   pre  { white-space: pre; }
   6   .annotation {
   7     font-size: 12px !important;
   8   }
   9   .dygraph-legend {
  10     width: 300px;
  11   }
  12 </style>
  13
  14 <h2>dygraphs Annotations</h2>
  15
  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
  19 them.</p>
  20
  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'),
  27     "dow.txt",
  28     {
  29       showRoller: true,
  30       customBars: true,
  31       labelsKMB: true,
  32     }
  33   );
  34
  35   stockchart.ready(function(g) {
  36     g.setAnnotations( [
  37     {
  38       series: "Real",
  39       x: "1929-08-15",
  40       shortText: "A",
  41       text: "1929 Stock Market Peak",
  42       cssClass: 'annotation'
  43     },
  44     {
  45       series: "Nominal",
  46       x: "1987-08-15",
  47       shortText: "B",
  48       text: "1987 Crash",
  49       cssClass: 'annotation'
  50     },
  51     {
  52       series: "Nominal",
  53       x: "1999-12-15",
  54       shortText: "C",
  55       text: "1999 (.com) Peak",
  56       cssClass: 'annotation'
  57     },
  58     {
  59       series: "Nominal",
  60       x: "2007-10-15",
  61       shortText: "D",
  62       text: "All-Time Market Peak",
  63       cssClass: 'annotation'
  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.ready(function() {
 104     g.setAnnotations([
 105     {
 106       series: &quot;Temperature&quot;,
 107       x: &quot;2008-05-08&quot;,
 108       shortText: &quot;L&quot;,
 109       text: &quot;Coldest Day&quot;
 110     }
 111     ]);
 112   });
 113 &lt;/script&gt;
 114 </pre>
 115 </div>
 116
 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">
 121     g = new Dygraph(
 122
 123       // containing div
 124       document.getElementById("graphdiv"),
 125
 126       // CSV or path to a CSV file.
 127       "Date,Temperature\n" +
 128       "2008-05-07,75\n" +
 129       "2008-05-08,70\n" +
 130       "2008-05-09,80\n"
 131     );
 132     g.ready(function() {
 133         g.setAnnotations([
 134         {
 135           series: "Temperature",
 136           x: "2008-05-08",
 137           shortText: "L",
 138           text: "Coldest Day"
 139         }
 140         ]);
 141     });
 142   </script>
 143 </div>
 144 </div>
 145
 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>
 147
 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>
 149
 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
 155 is attached:</p>
 156
 157 <pre>
 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
 162 </pre>
 163
 164 <p>For a more real-life example, see the <a
 165 href="tests/annotation.html">annotations demo</a></p>
 166
 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>
 173
 174 <pre>g = new Dygraph(div, "path/to/data.csv");
 175 g.ready(function() {
 176   // This is called when data.csv comes back and the chart draws.
 177   g.setAnnotations([
 178     &hellip;
 179   ]);
 180 });
 181 </pre>
 182
 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>
 185
 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>
 204 </table>
 205
 206 <h3>Annotation event handlers</h3>
 207
 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>
 210
 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>
 217 </table>
 218
 219 <p>These event handlers all take the same parameters:</p>
 220
 221 <pre>g.updateOptions( {
 222   annotationClickHandler: function(annotation, point, dygraph, event) {
 223     // ... access/modify annotation.series, annotation.x, ...
 224   }
 225 }); </pre>
 226
 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>
 229
 230 <!--#include virtual="footer.html" -->