[dygraphs.git] / docs / annotations.html

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7; IE=EmulateIE9">
    <title>dygraphs annotations</title>
    <style type="text/css">
      code { white-space: pre; }
      pre  { white-space: pre; }
      body { max-width: 800px; }
    </style>
    <!--[if IE]>
      <script type="text/javascript" src="excanvas.js"></script>
    <![endif]-->
    <script type="text/javascript" src="dygraph-combined.js"></script>
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <h2>dygraphs Annotations</h2>

    <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">
      // From http://www.econstats.com/eqty/eq_d_mi_3.csv
      stockchart = new Dygraph(
        document.getElementById('dow_chart'),
        "dow.txt",
        {
          showRoller: true,
          customBars: true,
          labelsKMB: true,
          labelsDivWidth: 300,
          drawCallback: function(g, is_initial) {
            if (!is_initial) return;

            g.setAnnotations( [
            {
              series: "Real",
              x: "1929-08-15",
              shortText: "A",
              text: "1929 Stock Market Peak"
            },
            {
              series: "Nominal",
              x: "1987-08-15",
              shortText: "B",
              text: "1987 Crash"
            },
            {
              series: "Nominal",
              x: "1999-12-15",
              shortText: "C",
              text: "1999 (.com) Peak"
            },
            {
              series: "Nominal",
              x: "2007-10-15",
              shortText: "D",
              text: "All-Time Market Peak"
            }
            ] );
          }
        }
      );
    </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>
&lt;script type=&quot;text/javascript&quot;&gt;
  g = new Dygraph(
    document.getElementById(&quot;graphdiv&quot;),
    &quot;Date,Temperature\n&quot; +
    &quot;2008-05-07,75\n&quot; +
    &quot;2008-05-08,70\n&quot; +
    &quot;2008-05-09,80\n&quot;
  );

  g.setAnnotations([
  {
    series: &quot;Temperature&quot;,
    x: &quot;2008-05-08&quot;,
    shortText: &quot;L&quot;,
    text: &quot;Coldest Day&quot;
  }
  ]);
&lt;/script&gt;
</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">
            g = new Dygraph(

              // containing div
              document.getElementById("graphdiv"),

              // CSV or path to a CSV file.
              "Date,Temperature\n" +
              "2008-05-07,75\n" +
              "2008-05-08,70\n" +
              "2008-05-09,80\n"
            );
            g.setAnnotations([
            {
              series: "Temperature",
              x: "2008-05-08",
              shortText: "L",
              text: "Coldest Day"
            }
            ]);
          </script>
        </div>
      </div>

  <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
  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 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> <td><b>Property</b></td><td><b>Description</b></td> </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</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>
  <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>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><td><b>Per-point field</b></td><td><b>Global option</b></td></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>

  <!-- Google Analytics -->
<script type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-769809-2']);
  _gaq.push(['_trackPageview']);
  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
</script>

  </body>
</html>
Commit	Line	Data
	1	<!DOCTYPE html>
	2	<html>
	3	<head>
	4	<meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7; IE=EmulateIE9">
	5	<title>dygraphs annotations</title>
	6	<style type="text/css">
	7	code { white-space: pre; }
	8	pre { white-space: pre; }
	9	body { max-width: 800px; }
	10	</style>
	11	<!--[if IE]>
	12	<script type="text/javascript" src="excanvas.js"></script>
	13	<![endif]-->
	14	<script type="text/javascript" src="dygraph-combined.js"></script>
	15	<link rel="stylesheet" href="style.css">
	16	</head>
	17	<body>
	18	<h2>dygraphs Annotations</h2>
	19
	20	<p>dygraphs lets you add annotations (markers) to individual points on your
	21	chart. These markers have a short bit of text or an icon that's displayed
	22	over the chart, plus a longer description that appears when you hover over
	23	them.</p>
	24
	25	<h3>Demo: Dow Jones Industrial Average</h3>
	26	<div id="dow_chart" style="width: 800px; height: 250px;"></div>
	27	<script type="text/javascript">
	28	// From http://www.econstats.com/eqty/eq_d_mi_3.csv
	29	stockchart = new Dygraph(
	30	document.getElementById('dow_chart'),
	31	"dow.txt",
	32	{
	33	showRoller: true,
	34	customBars: true,
	35	labelsKMB: true,
	36	labelsDivWidth: 300,
	37	drawCallback: function(g, is_initial) {
	38	if (!is_initial) return;
	39
	40	g.setAnnotations( [
	41	{
	42	series: "Real",
	43	x: "1929-08-15",
	44	shortText: "A",
	45	text: "1929 Stock Market Peak"
	46	},
	47	{
	48	series: "Nominal",
	49	x: "1987-08-15",
	50	shortText: "B",
	51	text: "1987 Crash"
	52	},
	53	{
	54	series: "Nominal",
	55	x: "1999-12-15",
	56	shortText: "C",
	57	text: "1999 (.com) Peak"
	58	},
	59	{
	60	series: "Nominal",
	61	x: "2007-10-15",
	62	shortText: "D",
	63	text: "All-Time Market Peak"
	64	}
	65	] );
	66	}
	67	}
	68	);
	69	</script>
	70
	71	<h3>Adding Annotations</h3>
	72
	73	<p>There are two methods which are used to add, remove and modify annotations:</p>
	74
	75	<table class="thinborder">
	76	<tr>
	77	<td><code>setAnnotations(array)</code></td>
	78	<td>Set the list of annotations currently displayed. This overwrites
	79	existing annotations and redraws the dygraph.</td>
	80	</tr>
	81	<tr>
	82	<td><code>annotations</code></td>
	83	<td>Returns an array of the currently-displayed annotations.</td>
	84	</tr>
	85	</table>
	86
	87	<p>Calling <code>dygraph.setAnnotations(dygraph.annotations())</code> is a
	88	no-op: it simply causes the chart to refresh.</p>
	89
	90	<p>Let's say we have a simple chart and wish to add an annotation. Here's how:</p>
	91
	92	<div class="example" style="clear:both;">
	93	<div class="codeblock" style="float:left;width:400px;">
	94	<h3 style="text-align:center">HTML</h3>
	95	<pre>
	96	<script type="text/javascript">
	97	g = new Dygraph(
	98	document.getElementById("graphdiv"),
	99	"Date,Temperature\n" +
	100	"2008-05-07,75\n" +
	101	"2008-05-08,70\n" +
	102	"2008-05-09,80\n"
	103	);
	104
	105	g.setAnnotations([
	106	{
	107	series: "Temperature",
	108	x: "2008-05-08",
	109	shortText: "L",
	110	text: "Coldest Day"
	111	}
	112	]);
	113	</script>
	114	</pre>
	115	</div>
	116	<div class="codeoutput" style="float:left;">
	117	<h3 style="text-align:center">OUTPUT</h3>
	118	<div id="graphdiv" style="width: 350px; height: 250px;"></div>
	119	<script type="text/javascript">
	120	g = new Dygraph(
	121
	122	// containing div
	123	document.getElementById("graphdiv"),
	124
	125	// CSV or path to a CSV file.
	126	"Date,Temperature\n" +
	127	"2008-05-07,75\n" +
	128	"2008-05-08,70\n" +
	129	"2008-05-09,80\n"
	130	);
	131	g.setAnnotations([
	132	{
	133	series: "Temperature",
	134	x: "2008-05-08",
	135	shortText: "L",
	136	text: "Coldest Day"
	137	}
	138	]);
	139	</script>
	140	</div>
	141	</div>
	142
	143	<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>
	144
	145	<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>
	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	<!-- Google Analytics -->
	212	<script type="text/javascript">
	213	var _gaq = _gaq \|\| [];
	214	_gaq.push(['_setAccount', 'UA-769809-2']);
	215	_gaq.push(['_trackPageview']);
	216	(function() {
	217	var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
	218	ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
	219	var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
	220	})();
	221	</script>
	222
	223	</body>
	224	</html>