client-freqwatch/Chart.js/docs/04-Polar-Area-Chart.md

   1 ---
   2 title: Polar Area Chart
   3 anchor: polar-area-chart
   4 ---
   5 ### Introduction
   6 Polar area charts are similar to pie charts, but each segment has the same angle - the radius of the segment differs depending on the value.
   7
   8 This type of chart is often useful when we want to show a comparison data similar to a pie chart, but also show a scale of values for context.
   9
  10 <div class="canvas-holder">
  11         <canvas width="250" height="125"></canvas>
  12 </div>
  13
  14 ### Example usage
  15
  16 ```javascript
  17 new Chart(ctx).PolarArea(data, options);
  18 ```
  19
  20 ### Data structure
  21
  22 ```javascript
  23 var data = [
  24         {
  25                 value: 300,
  26                 color:"#F7464A",
  27                 highlight: "#FF5A5E",
  28                 label: "Red"
  29         },
  30         {
  31                 value: 50,
  32                 color: "#46BFBD",
  33                 highlight: "#5AD3D1",
  34                 label: "Green"
  35         },
  36         {
  37                 value: 100,
  38                 color: "#FDB45C",
  39                 highlight: "#FFC870",
  40                 label: "Yellow"
  41         },
  42         {
  43                 value: 40,
  44                 color: "#949FB1",
  45                 highlight: "#A8B3C5",
  46                 label: "Grey"
  47         },
  48         {
  49                 value: 120,
  50                 color: "#4D5360",
  51                 highlight: "#616774",
  52                 label: "Dark Grey"
  53         }
  54
  55 ];
  56 ```
  57 As you can see, for the chart data you pass in an array of objects, with a value and a colour. The value attribute should be a number, while the color attribute should be a string. Similar to CSS, for this string you can use HEX notation, RGB, RGBA or HSL.
  58
  59 ### Chart options
  60
  61 These are the customisation options specific to Polar Area charts. These options are merged with the [global chart configuration options](#getting-started-global-chart-configuration), and form the options of the chart.
  62
  63 ```javascript
  64 {
  65         //Boolean - Show a backdrop to the scale label
  66         scaleShowLabelBackdrop : true,
  67
  68         //String - The colour of the label backdrop
  69         scaleBackdropColor : "rgba(255,255,255,0.75)",
  70
  71         // Boolean - Whether the scale should begin at zero
  72         scaleBeginAtZero : true,
  73
  74         //Number - The backdrop padding above & below the label in pixels
  75         scaleBackdropPaddingY : 2,
  76
  77         //Number - The backdrop padding to the side of the label in pixels
  78         scaleBackdropPaddingX : 2,
  79
  80         //Boolean - Show line for each value in the scale
  81         scaleShowLine : true,
  82
  83         //Boolean - Stroke a line around each segment in the chart
  84         segmentShowStroke : true,
  85
  86         //String - The colour of the stroke on each segment.
  87         segmentStrokeColor : "#fff",
  88
  89         //Number - The width of the stroke value in pixels
  90         segmentStrokeWidth : 2,
  91
  92         //Number - Amount of animation steps
  93         animationSteps : 100,
  94
  95         //String - Animation easing effect.
  96         animationEasing : "easeOutBounce",
  97
  98         //Boolean - Whether to animate the rotation of the chart
  99         animateRotate : true,
 100
 101         //Boolean - Whether to animate scaling the chart from the centre
 102         animateScale : false,
 103         {% raw %}
 104         //String - A legend template
 105         legendTemplate : "<ul class=\"<%=name.toLowerCase()%>-legend\"><% for (var i=0; i<segments.length; i++){%><li><span style=\"background-color:<%=segments[i].fillColor%>\"></span><%if(segments[i].label){%><%=segments[i].label%><%}%></li><%}%></ul>"
 106         {% endraw %}
 107 }
 108 ```
 109
 110 You can override these for your `Chart` instance by passing a second argument into the `PolarArea` method as an object with the keys you want to override.
 111
 112 For example, we could have a polar area chart with a black stroke on each segment like so:
 113
 114 ```javascript
 115 new Chart(ctx).PolarArea(data, {
 116         segmentStrokeColor: "#000000"
 117 });
 118 // This will create a chart with all of the default options, merged from the global config,
 119 // and the PolarArea chart defaults but this particular instance will have `segmentStrokeColor` set to `"#000000"`.
 120 ```
 121
 122 We can also change these defaults values for each PolarArea type that is created, this object is available at `Chart.defaults.PolarArea`.
 123
 124 ### Prototype methods
 125
 126 #### .getSegmentsAtEvent( event )
 127
 128 Calling `getSegmentsAtEvent(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the segment elements that are at that the same position of that event.
 129
 130 ```javascript
 131 canvas.onclick = function(evt){
 132         var activePoints = myPolarAreaChart.getSegmentsAtEvent(evt);
 133         // => activePoints is an array of segments on the canvas that are at the same position as the click event.
 134 };
 135 ```
 136
 137 This functionality may be useful for implementing DOM based tooltips, or triggering custom behaviour in your application.
 138
 139 #### .update( )
 140
 141 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.
 142
 143 ```javascript
 144 myPolarAreaChart.segments[1].value = 10;
 145 // Would update the first dataset's value of 'Green' to be 10
 146 myPolarAreaChart.update();
 147 // Calling update now animates the position of Green from 50 to 10.
 148 ```
 149
 150 #### .addData( segmentData, index )
 151
 152 Calling `addData(segmentData, index)` on your Chart instance passing an object in the same format as in the constructor. There is an option second argument of 'index', this determines at what index the new segment should be inserted into the chart.
 153
 154 ```javascript
 155 // An object in the same format as the original data source
 156 myPolarAreaChart.addData({
 157         value: 130,
 158         color: "#B48EAD",
 159         highlight: "#C69CBE",
 160         label: "Purple"
 161 });
 162 // The new segment will now animate in.
 163 ```
 164
 165 #### .removeData( index )
 166
 167 Calling `removeData(index)` on your Chart instance will remove segment at that particular index. If none is provided, it will default to the last segment.
 168
 169 ```javascript
 170 myPolarAreaChart.removeData();
 171 // Other segments will update to fill the empty space left.
 172 ```