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