dygraphs

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Dygraphs — annotations</title> <link rel="stylesheet" type="text/css" href=".jslibs/bootstrap.min.css" /> <link rel="stylesheet" type="text/css" href="dist/dygraph.css" /> <link rel="stylesheet" type="text/css" href="common/vextlnk.css" /> <link rel="stylesheet" type="text/css" href="site.css" /> <script type="text/javascript" src=".jslibs/jquery.min.js"></script> <script type="text/javascript" src=".jslibs/bootstrap.min.js"></script> <script type="text/javascript" src="dist/dygraph.js"></script> </head> <body> <nav id="header" class="navbar navbar-default navbar-fixed-top"> <div class="container-fluid"> <div class="navbar-header"> <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar-responsive-collapse" aria-expanded="false"> <span class="sr-only">Toggle navigation</span> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button> <a class="navbar-brand" href="/">dygraphs</a> </div> <div class="collapse navbar-collapse" id="navbar-responsive-collapse">  <ul class="nav navbar-nav"> <li class="dropdown"> <a class="dropdown-toggle" id="drop3" role="button" data-toggle="dropdown" href="#">Documentation<b class="caret"></b></a> <ul id="menu0" class="dropdown-menu" role="menu" aria-labelledby="drop3"> <li role="presentation"><a role="menuitem" tabindex="-1" href="tutorial.html">Tutorial</a></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="options.html">Options Reference</a></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="jsdoc/symbols/Dygraph.html">API Reference</a></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="data.html">Data Format</a></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="annotations.html">Annotations</a></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="css.html">CSS Reference</a></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="versions.html">Version History</a></li> <li role="separator" class="divider"></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="ie.html">Notes on Internet Explorer</a></li> </ul> </li> <li class="dropdown"> <a class="dropdown-toggle" id="drop4" role="button" data-toggle="dropdown" href="#">Examples<b class="caret"></b></a> <ul id="menu1" class="dropdown-menu" role="menu" aria-labelledby="drop4"> <li role="presentation"><a role="menuitem" tabindex="-1" href="gallery/">Demo Gallery</a></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="users.html">List of Users</a></li> <li role="separator" class="divider"></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="tests/">Test Cases</a></li> <li role="separator" class="divider"></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="https://dygraphs.com/fiddle/">Play</a></li> </ul> </li> <li><a class="xnavbar-link" href="download.html">Download</a></li> <li class="dropdown"> <a class="dropdown-toggle" id="drop7" role="button" data-toggle="dropdown" href="#">Community <b class="caret"></b></a> <ul id="menu4" class="dropdown-menu" role="menu" aria-labelledby="drop7"> <li role="presentation"><a role="menuitem" tabindex="-1" href="http://blog.dygraphs.com/">Blog</a></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="https://stackoverflow.com/questions/ask?tags=dygraphs+javascript">Ask a Question</a></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="https://stackoverflow.com/questions/tagged/dygraphs">Stack Overflow</a></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="https://groups.google.com/g/dygraphs-users">Mailing List</a></li> </ul> </li> <li class="dropdown"> <a class="dropdown-toggle" id="drop6" role="button" data-toggle="dropdown" href="#">Contribute <b class="caret"></b></a> <ul id="menu3" class="dropdown-menu" role="menu" aria-labelledby="drop6"> <li role="presentation"><a role="menuitem" tabindex="-1" href="changes.html">Contributors Guide</a></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/danvk/dygraphs">Source (Github)</a></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/danvk/dygraphs/issues">Issue Tracker</a></li> <li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/danvk/dygraphs/issues/new">Report a Bug</a></li> </ul> </li> </ul> </div> </div> </nav> <div class="container" id="main"> <div class="row"> <div class="col-lg-12"> <h2>dygraphs Annotations</h2><div class="annotationpage"> <p>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.</p> <h3>Demo: Dow Jones Industrial Average</h3> <div id="dow_chart" style="width: 800px; height: 250px;"></div> <script type="text/javascript"><![CDATA[//><!]]></script> <h3>Adding Annotations</h3> <p>There are two methods which are used to add, remove and modify annotations:</p> <table class="thinborder"> <tr> <td><code>setAnnotations(array)</code></td> <td>Set the list of annotations currently displayed. This overwrites existing annotations and redraws the dygraph.</td> </tr> <tr> <td><code>annotations</code></td> <td>Returns an array of the currently-displayed annotations.</td> </tr> </table> <p>Calling <code>dygraph.setAnnotations(dygraph.annotations())</code> is a no-op: it simply causes the chart to refresh.</p> <p>Let's say we have a simple chart and wish to add an annotation. Here's how:</p> <div class="example" style="clear:both;"> <div class="codeblock" style="float:left;width:400px;"> <h3 style="text-align:center">HTML</h3> <pre> <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> </pre> </div> <div class="codeoutput" style="float:left;"> <h3 style="text-align:center">OUTPUT</h3> <div id="graphdiv" style="width: 350px; height: 250px;"></div> <script type="text/javascript"><![CDATA[//><!]]></script> </div> </div> <p style="clear:both">Annotations are JavaScript dictionaries. The <code>series</code> and either <code>x</code> or <code>xval</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> <p id="xvalformat">If you are using the <a href="data.html#array">native data format</a>, you need to pass in a numeric value for the <code>xval</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 milliseconds since the epoch, for example from <code>Date.parse('YYYY/MM/DD')</code>, <code>dateObject.getTime()</code> or <code>moment().valueOf()</code>. As an alternative, use the <code>x</code> field, see table below.</p> <h3>Modifying Annotations</h3> <p>To remove or modify existing annotations, call the <code>annotations</code> method to get an array of annotations. Modify that array, then pass it back in to <code>setAnnotations</code>. For example, this code deletes the second annotation and changes the series to which the first is attached:</p> <pre> var annotations = g.annotations(); annotations.splice(1,1); // remove the second annotation annotations[0].series = "Series 2"; g.setAnnotations(annotations); // causes a redraw </pre> <p>For a more real-life example, see the <a href="tests/annotation.html">annotations demo</a></p> <h3>Annotations and Data Sources</h3> <p>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 <code>new Dygraph</code> and so the call to <code>g.setAnnotations</code> will fail. The best way around this is to use the <code>ready()</code> method:</p> <pre>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([ … ]); }); </pre> <h3>Annotations property reference</h3> <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> <table class="thinborder"> <tr><th>Property</th><th>Description</th></tr> <tr><td><code>series</code></td><td><i>(required)</i> The name of the series to which the annotated point belongs.</td></tr> <tr><td><code>x</code></td><td><i>(required unless xval is given)</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". As an alternative, use the <code>xval</code> field.</td></tr> <tr><td><code>xval</code></td><td><i>(required unless x is given)</i> The numeric x value of the point, milliseconds since the epoch for a Date x axis (see <a href="#xvalformat">above</a>). As an alternative, use the <code>x</code> field.</td></tr> <tr><td><code>shortText</code></td><td>Text that will appear on the annotation's flag.</td></tr> <tr><td><code>text</code></td><td>A longer description of the annotation which will appear when the user hovers over it.</td></tr> <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> <tr><td><code>width</code></td><td>Width (in pixels) of the annotation flag or icon.</td></tr> <tr><td><code>height</code></td><td>Height (in pixels) of the annotation flag or icon.</td></tr> <tr><td><code>cssClass</code></td><td>CSS class to use for styling the annotation.</td></tr> <tr><td><code>tickHeight</code></td><td>Height of the tick mark (in pixels) connecting the point to its flag or icon.</td></tr> <tr><td><code>tickWidth</code></td><td>Width of the tick mark connecting the point to its flag or icon.</td></tr> <tr><td><code>tickColor</code></td><td>Color of the tick mark connecting the point to its flag or icon.</td></tr> <tr><td><code>attachAtBottom</code></td><td>If true, attach annotations to the x-axis, rather than to actual points.</td></tr> <tr><td><code>clickHandler</code></td> <td>See Handlers, below</td></tr> <tr><td><code>mouseOverHandler</code></td><td>See Handlers, below</td></tr> <tr><td><code>mouseOutHandler</code></td> <td>See Handlers, below</td></tr> <tr><td><code>dblClickHandler</code></td> <td>See Handlers, below</td></tr> </table> <h3>Annotation event handlers</h3> <p>dygraphs lets you attach event handlers to your annotations. These can be specified globally (for all annotations) or on a per-annotation basis:</p> <table class="thinborder"> <tr><th>Per-point field</th><th>Global option</th></tr> <tr><td><code>clickHandler</code></td> <td><code>annotationClickHandler</code></td></tr> <tr><td><code>mouseOverHandler</code></td><td><code>annotationMouseOverHandler</code></td></tr> <tr><td><code>mouseOutHandler</code></td> <td><code>annotationMouseOutHandler</code></td></tr> <tr><td><code>dblClickHandler</code></td> <td><code>annotationDblClickHandler</code></td></tr> </table> <p>These event handlers all take the same parameters:</p> <pre>g.updateOptions( { annotationClickHandler: function(annotation, point, dygraph, event) { // ... access/modify annotation.series, annotation.x, ... } });</pre> <p>Again, check out the <a href="tests/annotation.html">annotations demo</a> for concrete examples of usage of all these handlers.</p> </div> </div>  </div>  </div>    </body> </html>