Add jsdoc for setAnnotations() and an example of how to use them with…

… native-format dates.
MauroJr · Dec 9, 2011 · 41ee764 · 41ee764
1 parent fbff6d7
commit 41ee764
Show file tree

Hide file tree

Showing 3 changed files with 47 additions and 0 deletions.
diff --git a/docs/annotations.html b/docs/annotations.html
@@ -142,6 +142,8 @@ <h3 style="text-align:center">OUTPUT</h3>
 
   <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>
 
+  <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>
+
   <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

diff --git a/dygraph.js b/dygraph.js
@@ -2969,6 +2969,9 @@ Dygraph.prototype.size = function() {
 
 /**
  * Update the list of annotations and redraw the chart.
+ * See dygraphs.com/annotations.html for more info on how to use annotations.
+ * @param ann {Array} An array of annotation objects.
+ * @param suppressDraw {Boolean} Set to "true" to block chart redraw (optional).
  */
 Dygraph.prototype.setAnnotations = function(ann, suppressDraw) {
   // Only add the annotation CSS rule once we know it will be used.

diff --git a/tests/annotation-native.html b/tests/annotation-native.html
@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7; IE=EmulateIE9">
+    <title>Native format annotations</title>
+    <!--[if IE]>
+    <script type="text/javascript" src="../excanvas.js"></script>
+    <![endif]-->
+    <script type="text/javascript" src="../dygraph-dev.js"></script>
+  </head>
+  <body>
+    <p>This test demonstrates how annotations can be used with <a href="http://dygraphs.com/data.html#array">native-format</a> data.</p>
+
+    <div id="demodiv"></div>
+
+    <script type="text/javascript">
+      g = new Dygraph(
+              document.getElementById("demodiv"),
+              [
+                [ new Date("2011/11/01"), 100 ],
+                [ new Date("2011/11/02"), 200 ],
+                [ new Date("2011/11/03"), 300 ],
+                [ new Date("2011/11/04"), 100 ],
+                [ new Date("2011/11/05"), 200 ],
+                [ new Date("2011/11/06"), 300 ],
+                [ new Date("2011/11/07"), 200 ],
+                [ new Date("2011/11/08"), 100 ]
+              ],
+              {
+                labels: [ 'Date', 'Value' ]
+              }
+          );
+
+      g.setAnnotations([{
+        series: 'Value',
+        x: Date.parse('2011/11/04'),
+        shortText: 'M',
+        text: 'Marker'
+      }]);
+    </script>
+</body>
+</html>