## dygraphs Annotations

dygraphs lets you add annotations (markers) to individual points on your chart. These markers have a short bit of text or an icon that's displayed over the chart, plus a longer description that appears when you hover over them.

### Demo: Dow Jones Industrial Average

### Adding Annotations

There are two methods which are used to add, remove and modify annotations:

`setAnnotations(array)` | Set the list of annotations currently displayed. This overwrites existing annotations and redraws the dygraph.
`annotations` | Returns an array of the currently-displayed annotations.

Calling `dygraph.setAnnotations(dygraph.annotations())` is a no-op: it simply causes the chart to refresh.

Let's say we have a simple chart and wish to add an annotation. Here's how:

### HTML

    <script type="text/javascript">
    Dygraph.onDOMready(function onDOMready() {
      g = new Dygraph(
        document.getElementById("graphdiv"),
        "Date,Temperature\n" +
        "2008-05-07,75\n" +
        "2008-05-08,70\n" +
        "2008-05-09,80\n"
      );

      g.ready(function() {
        g.setAnnotations([
        {
          series: "Temperature",
          x: "2008-05-08",
          shortText: "L",
          text: "Coldest Day"
        }
        ]);
      });
    });
    </script>

### OUTPUT

Annotations are JavaScript dictionaries. The `series` and either `x` or `xval` fields are required: they indicate which point the annotation should be attached to. If specified, `shortText` will appear on the annotation "flag". If you don't specify `shortText`, you can specify `icon` instead to display a small picture. The `text` parameter specifies hovertext. If you highlight the annotation and leave the mouse still, it will appear.

If you are using the native data format, you need to pass in a numeric value for the `xval` 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 milliseconds since the epoch, for example from `Date.parse('YYYY/MM/DD')`, `dateObject.getTime()` or `moment().valueOf()`. As an alternative, use the `x` field, see table below.

### Modifying Annotations

To remove or modify existing annotations, call the `annotations` method to get an array of annotations. Modify that array, then pass it back in to `setAnnotations`. For example, this code deletes the second annotation and changes the series to which the first is attached:

    var annotations = g.annotations();
    annotations.splice(1,1);  // remove the second annotation
    annotations[0].series = "Series 2";
    g.setAnnotations(annotations);  // causes a redraw

For a more real-life example, see the annotations demo

### Annotations and Data Sources

When you pass a URL as the data source to dygraphs, it must issue a request for the data before drawing the chart. This means that the chart data is not yet available immediately after you call `new Dygraph` and so the call to `g.setAnnotations` will fail. The best way around this is to use the `ready()` method:

    g = new Dygraph(div, "path/to/data.csv");
    g.ready(function() {
      // This is called when data.csv comes back and the chart draws.
      g.setAnnotations([
        …
      ]);
    });

### Annotations property reference

These properties can all be set in the dictionary for an annotation. The use of each one is demonstrated on the annotations demo page.

Property | Description
--- | ---
`series` | (required) The name of the series to which the annotated point belongs.
`x` | (required unless xval is given) 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". As an alternative, use the `xval` field.
`xval` | (required unless x is given) The numeric x value of the point, milliseconds since the epoch for a Date x axis (see above). As an alternative, use the `x` field.
`shortText` | Text that will appear on the annotation's flag.
`text` | A longer description of the annotation which will appear when the user hovers over it.
`icon` | Specify in place of `shortText` to mark the annotation with an image rather than text. If you specify this, you must specify `width` and `height`.
`width` | Width (in pixels) of the annotation flag or icon.
`height` | Height (in pixels) of the annotation flag or icon.
`cssClass` | CSS class to use for styling the annotation.
`tickHeight` | Height of the tick mark (in pixels) connecting the point to its flag or icon.
`tickWidth` | Width of the tick mark connecting the point to its flag or icon.
`tickColor` | Color of the tick mark connecting the point to its flag or icon.
`attachAtBottom` | If true, attach annotations to the x-axis, rather than to actual points.
`clickHandler` | See Handlers, below
`mouseOverHandler` | See Handlers, below
`mouseOutHandler` | See Handlers, below
`dblClickHandler` | See Handlers, below

### Annotation event handlers

dygraphs lets you attach event handlers to your annotations. These can be specified globally (for all annotations) or on a per-annotation basis:

Per-point field | Global option
--- | ---
`clickHandler` | `annotationClickHandler`
`mouseOverHandler` | `annotationMouseOverHandler`
`mouseOutHandler` | `annotationMouseOutHandler`
`dblClickHandler` | `annotationDblClickHandler`

These event handlers all take the same parameters:

    g.updateOptions( {
      annotationClickHandler: function(annotation, point, dygraph, event) {
        // ... access/modify annotation.series, annotation.x, ...
      }
    });

Again, check out the annotations demo for concrete examples of usage of all these handlers.