client-freqwatch/Chart.js/docs/02-Bar-Chart.md

   1 ---
   2 title: Bar Chart
   3 anchor: bar-chart
   4 ---
   5
   6 ### Introduction
   7 A bar chart is a way of showing data as bars.
   8
   9 It is sometimes used to show trend data, and the comparison of multiple data sets side by side.
  10
  11 <div class="canvas-holder">
  12         <canvas width="250" height="125"></canvas>
  13 </div>
  14
  15 ### Example usage
  16 ```javascript
  17 var myBarChart = new Chart(ctx).Bar(data, options);
  18 ```
  19
  20 ### Data structure
  21
  22 ```javascript
  23 var data = {
  24         labels: ["January", "February", "March", "April", "May", "June", "July"],
  25         datasets: [
  26                 {
  27                         label: "My First dataset",
  28                         fillColor: "rgba(220,220,220,0.5)",
  29                         strokeColor: "rgba(220,220,220,0.8)",
  30                         highlightFill: "rgba(220,220,220,0.75)",
  31                         highlightStroke: "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.5)",
  37                         strokeColor: "rgba(151,187,205,0.8)",
  38                         highlightFill: "rgba(151,187,205,0.75)",
  39                         highlightStroke: "rgba(151,187,205,1)",
  40                         data: [28, 48, 40, 19, 86, 27, 90]
  41                 }
  42         ]
  43 };
  44 ```
  45 The bar chart has the a very similar data structure to the line chart, and has an array of datasets, each with colours and an array of data. Again, colours are in CSS format.
  46 We have an array of labels too for display. In the example, we are showing the same data as the previous line chart example.
  47
  48 The label key on each dataset is optional, and can be used when generating a scale for the chart.
  49
  50 ### Chart Options
  51
  52 These are the customisation options specific to Bar charts. These options are merged with the [global chart configuration options](#getting-started-global-chart-configuration), and form the options of the chart.
  53
  54 ```javascript
  55 {
  56         //Boolean - Whether the scale should start at zero, or an order of magnitude down from the lowest value
  57         scaleBeginAtZero : true,
  58
  59         //Boolean - Whether grid lines are shown across the chart
  60         scaleShowGridLines : true,
  61
  62         //String - Colour of the grid lines
  63         scaleGridLineColor : "rgba(0,0,0,.05)",
  64
  65         //Number - Width of the grid lines
  66         scaleGridLineWidth : 1,
  67
  68         //Boolean - Whether to show horizontal lines (except X axis)
  69         scaleShowHorizontalLines: true,
  70
  71         //Boolean - Whether to show vertical lines (except Y axis)
  72         scaleShowVerticalLines: true,
  73
  74         //Boolean - If there is a stroke on each bar
  75         barShowStroke : true,
  76
  77         //Number - Pixel width of the bar stroke
  78         barStrokeWidth : 2,
  79
  80         //Number - Spacing between each of the X value sets
  81         barValueSpacing : 5,
  82
  83         //Number - Spacing between data sets within X values
  84         barDatasetSpacing : 1,
  85         {% raw %}
  86         //String - A legend template
  87         legendTemplate : "<ul class=\"<%=name.toLowerCase()%>-legend\"><% for (var i=0; i<datasets.length; i++){%><li><span style=\"background-color:<%=datasets[i].fillColor%>\"></span><%if(datasets[i].label){%><%=datasets[i].label%><%}%></li><%}%></ul>"
  88         {% endraw %}
  89 }
  90 ```
  91
  92 You can override these for your `Chart` instance by passing a second argument into the `Bar` method as an object with the keys you want to override.
  93
  94 For example, we could have a bar chart without a stroke on each bar by doing the following:
  95
  96 ```javascript
  97 new Chart(ctx).Bar(data, {
  98         barShowStroke: false
  99 });
 100 // This will create a chart with all of the default options, merged from the global config,
 101 //  and the Bar chart defaults but this particular instance will have `barShowStroke` set to false.
 102 ```
 103
 104 We can also change these defaults values for each Bar type that is created, this object is available at `Chart.defaults.Bar`.
 105
 106 ### Prototype methods
 107
 108 #### .getBarsAtEvent( event )
 109
 110 Calling `getBarsAtEvent(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the bar elements that are at that the same position of that event.
 111
 112 ```javascript
 113 canvas.onclick = function(evt){
 114         var activeBars = myBarChart.getBarsAtEvent(evt);
 115         // => activeBars is an array of bars on the canvas that are at the same position as the click event.
 116 };
 117 ```
 118
 119 This functionality may be useful for implementing DOM based tooltips, or triggering custom behaviour in your application.
 120
 121 #### .update( )
 122
 123 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.
 124
 125 ```javascript
 126 myBarChart.datasets[0].bars[2].value = 50;
 127 // Would update the first dataset's value of 'March' to be 50
 128 myBarChart.update();
 129 // Calling update now animates the position of March from 90 to 50.
 130 ```
 131
 132 #### .addData( valuesArray, label )
 133
 134 Calling `addData(valuesArray, label)` on your Chart instance passing an array of values for each dataset, along with a label for those bars.
 135
 136 ```javascript
 137 // The values array passed into addData should be one for each dataset in the chart
 138 myBarChart.addData([40, 60], "August");
 139 // The new data will now animate at the end of the chart.
 140 ```
 141
 142 #### .removeData( )
 143
 144 Calling `removeData()` on your Chart instance will remove the first value for all datasets on the chart.
 145
 146 ```javascript
 147 myBarChart.removeData();
 148 // The chart will now animate and remove the first bar
 149 ```