client-freqwatch/Chart.js/docs/01-Line-Chart.md

   1 ---
   2 title: Line Chart
   3 anchor: line-chart
   4 ---
   5 ###Introduction
   6 A line chart is a way of plotting data points on a line.
   7
   8 Often, it is used to show trend data, and the comparison of two data sets.
   9
  10 <div class="canvas-holder">
  11         <canvas width="250" height="125"></canvas>
  12 </div>
  13
  14 ###Example usage
  15 ```javascript
  16 var myLineChart = new Chart(ctx).Line(data, options);
  17 ```
  18 ###Data structure
  19
  20 ```javascript
  21 var data = {
  22         labels: ["January", "February", "March", "April", "May", "June", "July"],
  23         datasets: [
  24                 {
  25                         label: "My First dataset",
  26                         fillColor: "rgba(220,220,220,0.2)",
  27                         strokeColor: "rgba(220,220,220,1)",
  28                         pointColor: "rgba(220,220,220,1)",
  29                         pointStrokeColor: "#fff",
  30                         pointHighlightFill: "#fff",
  31                         pointHighlightStroke: "rgba(220,220,220,1)",
  32                         data: [65, 59, 80, 81, 56, 55, 40]
  33                 },
  34                 {
  35                         label: "My Second dataset",
  36                         fillColor: "rgba(151,187,205,0.2)",
  37                         strokeColor: "rgba(151,187,205,1)",
  38                         pointColor: "rgba(151,187,205,1)",
  39                         pointStrokeColor: "#fff",
  40                         pointHighlightFill: "#fff",
  41                         pointHighlightStroke: "rgba(151,187,205,1)",
  42                         data: [28, 48, 40, 19, 86, 27, 90]
  43                 }
  44         ]
  45 };
  46 ```
  47
  48 The line chart requires an array of labels for each of the data points. This is shown on the X axis.
  49 The data for line charts is broken up into an array of datasets. Each dataset has a colour for the fill, a colour for the line and colours for the points and strokes of the points. These colours are strings just like CSS. You can use RGBA, RGB, HEX or HSL notation.
  50
  51 The label key on each dataset is optional, and can be used when generating a scale for the chart.
  52
  53 ### Chart options
  54
  55 These are the customisation options specific to Line charts. These options are merged with the [global chart configuration options](#getting-started-global-chart-configuration), and form the options of the chart.
  56
  57 ```javascript
  58 {
  59
  60         ///Boolean - Whether grid lines are shown across the chart
  61         scaleShowGridLines : true,
  62
  63         //String - Colour of the grid lines
  64         scaleGridLineColor : "rgba(0,0,0,.05)",
  65
  66         //Number - Width of the grid lines
  67         scaleGridLineWidth : 1,
  68
  69         //Boolean - Whether to show horizontal lines (except X axis)
  70         scaleShowHorizontalLines: true,
  71
  72         //Boolean - Whether to show vertical lines (except Y axis)
  73         scaleShowVerticalLines: true,
  74
  75         //Boolean - Whether the line is curved between points
  76         bezierCurve : true,
  77
  78         //Number - Tension of the bezier curve between points
  79         bezierCurveTension : 0.4,
  80
  81         //Boolean - Whether to show a dot for each point
  82         pointDot : true,
  83
  84         //Number - Radius of each point dot in pixels
  85         pointDotRadius : 4,
  86
  87         //Number - Pixel width of point dot stroke
  88         pointDotStrokeWidth : 1,
  89
  90         //Number - amount extra to add to the radius to cater for hit detection outside the drawn point
  91         pointHitDetectionRadius : 20,
  92
  93         //Boolean - Whether to show a stroke for datasets
  94         datasetStroke : true,
  95
  96         //Number - Pixel width of dataset stroke
  97         datasetStrokeWidth : 2,
  98
  99         //Boolean - Whether to fill the dataset with a colour
 100         datasetFill : true,
 101         {% raw %}
 102         //String - A legend template
 103         legendTemplate : "<ul class=\"<%=name.toLowerCase()%>-legend\"><% for (var i=0; i<datasets.length; i++){%><li><span style=\"background-color:<%=datasets[i].strokeColor%>\"></span><%if(datasets[i].label){%><%=datasets[i].label%><%}%></li><%}%></ul>"
 104         {% endraw %}
 105
 106         //Boolean - Whether to horizontally center the label and point dot inside the grid
 107         offsetGridLines : false
 108 };
 109 ```
 110
 111 You can override these for your `Chart` instance by passing a second argument into the `Line` method as an object with the keys you want to override.
 112
 113 For example, we could have a line chart without bezier curves between points by doing the following:
 114
 115 ```javascript
 116 new Chart(ctx).Line(data, {
 117         bezierCurve: false
 118 });
 119 // This will create a chart with all of the default options, merged from the global config,
 120 // and the Line chart defaults, but this particular instance will have `bezierCurve` set to false.
 121 ```
 122
 123 We can also change these defaults values for each Line type that is created, this object is available at `Chart.defaults.Line`.
 124
 125
 126 ### Prototype methods
 127
 128 #### .getPointsAtEvent( event )
 129
 130 Calling `getPointsAtEvent(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the point elements that are at that the same position of that event.
 131
 132 ```javascript
 133 canvas.onclick = function(evt){
 134         var activePoints = myLineChart.getPointsAtEvent(evt);
 135         // => activePoints is an array of points on the canvas that are at the same position as the click event.
 136 };
 137 ```
 138
 139 This functionality may be useful for implementing DOM based tooltips, or triggering custom behaviour in your application.
 140
 141 #### .update( )
 142
 143 Calling `update()` on your Chart instance will re-render the chart with any updated values, allowing you to edit the value of multiple existing points, then render those in one animated render loop.
 144
 145 ```javascript
 146 myLineChart.datasets[0].points[2].value = 50;
 147 // Would update the first dataset's value of 'March' to be 50
 148 myLineChart.update();
 149 // Calling update now animates the position of March from 90 to 50.
 150 ```
 151
 152 #### .addData( valuesArray, label )
 153
 154 Calling `addData(valuesArray, label)` on your Chart instance passing an array of values for each dataset, along with a label for those points.
 155
 156 ```javascript
 157 // The values array passed into addData should be one for each dataset in the chart
 158 myLineChart.addData([40, 60], "August");
 159 // This new data will now animate at the end of the chart.
 160 ```
 161
 162 #### .removeData( )
 163
 164 Calling `removeData()` on your Chart instance will remove the first value for all datasets on the chart.
 165
 166 ```javascript
 167 myLineChart.removeData();
 168 // The chart will remove the first point and animate other points into place
 169 ```