client-freqwatch/Chart.js/docs/06-Advanced.md

   1 ---
   2 title: Advanced usage
   3 anchor: advanced-usage
   4 ---
   5
   6
   7 ### Prototype methods
   8
   9 For each chart, there are a set of global prototype methods on the shared `ChartType` which you may find useful. These are available on all charts created with Chart.js, but for the examples, let's use a line chart we've made.
  10
  11 ```javascript
  12 // For example:
  13 var myLineChart = new Chart(ctx).Line(data);
  14 ```
  15
  16 #### .clear()
  17
  18 Will clear the chart canvas. Used extensively internally between animation frames, but you might find it useful.
  19
  20 ```javascript
  21 // Will clear the canvas that myLineChart is drawn on
  22 myLineChart.clear();
  23 // => returns 'this' for chainability
  24 ```
  25
  26 #### .stop()
  27
  28 Use this to stop any current animation loop. This will pause the chart during any current animation frame. Call `.render()` to re-animate.
  29
  30 ```javascript
  31 // Stops the charts animation loop at its current frame
  32 myLineChart.stop();
  33 // => returns 'this' for chainability
  34 ```
  35
  36 #### .resize()
  37
  38 Use this to manually resize the canvas element. This is run each time the browser is resized, but you can call this method manually if you change the size of the canvas nodes container element.
  39
  40 ```javascript
  41 // Resizes & redraws to fill its container element
  42 myLineChart.resize();
  43 // => returns 'this' for chainability
  44 ```
  45
  46 #### .destroy()
  47
  48 Use this to destroy any chart instances that are created. This will clean up any references stored to the chart object within Chart.js, along with any associated event listeners attached by Chart.js.
  49
  50 ```javascript
  51 // Destroys a specific chart instance
  52 myLineChart.destroy();
  53 ```
  54
  55 #### .toBase64Image()
  56
  57 This returns a base 64 encoded string of the chart in it's current state.
  58
  59 ```javascript
  60 myLineChart.toBase64Image();
  61 // => returns png data url of the image on the canvas
  62 ```
  63
  64 #### .generateLegend()
  65
  66 Returns an HTML string of a legend for that chart. The template for this legend is at `legendTemplate` in the chart options.
  67
  68 ```javascript
  69 myLineChart.generateLegend();
  70 // => returns HTML string of a legend for this chart
  71 ```
  72
  73 ### External Tooltips
  74
  75 You can enable custom tooltips in the global or chart configuration like so:
  76
  77 ```javascript
  78 var myPieChart = new Chart(ctx).Pie(data, {
  79         customTooltips: function(tooltip) {
  80
  81         // tooltip will be false if tooltip is not visible or should be hidden
  82         if (!tooltip) {
  83             return;
  84         }
  85
  86         // Otherwise, tooltip will be an object with all tooltip properties like:
  87
  88         // tooltip.caretHeight
  89         // tooltip.caretPadding
  90         // tooltip.chart
  91         // tooltip.cornerRadius
  92         // tooltip.fillColor
  93         // tooltip.font...
  94         // tooltip.text
  95         // tooltip.x
  96         // tooltip.y
  97         // etc...
  98
  99     };
 100 });
 101 ```
 102
 103 See files `sample/pie-customTooltips.html` and `sample/line-customTooltips.html` for examples on how to get started.
 104
 105
 106 ### Writing new chart types
 107
 108 Chart.js 1.0 has been rewritten to provide a platform for developers to create their own custom chart types, and be able to share and utilise them through the Chart.js API.
 109
 110 The format is relatively simple, there are a set of utility helper methods under `Chart.helpers`, including things such as looping over collections, requesting animation frames, and easing equations.
 111
 112 On top of this, there are also some simple base classes of Chart elements, these all extend from `Chart.Element`, and include things such as points, bars and scales.
 113
 114 ```javascript
 115 Chart.Type.extend({
 116         // Passing in a name registers this chart in the Chart namespace
 117         name: "Scatter",
 118         // Providing a defaults will also register the deafults in the chart namespace
 119         defaults : {
 120                 options: "Here",
 121                 available: "at this.options"
 122         },
 123         // Initialize is fired when the chart is initialized - Data is passed in as a parameter
 124         // Config is automatically merged by the core of Chart.js, and is available at this.options
 125         initialize:  function(data){
 126                 this.chart.ctx // The drawing context for this chart
 127                 this.chart.canvas // the canvas node for this chart
 128         },
 129         // Used to draw something on the canvas
 130         draw: function() {
 131         }
 132 });
 133
 134 // Now we can create a new instance of our chart, using the Chart.js API
 135 new Chart(ctx).Scatter(data);
 136 // initialize is now run
 137 ```
 138
 139 ### Extending existing chart types
 140
 141 We can also extend existing chart types, and expose them to the API in the same way. Let's say for example, we might want to run some more code when we initialize every Line chart.
 142
 143 ```javascript
 144 // Notice now we're extending the particular Line chart type, rather than the base class.
 145 Chart.types.Line.extend({
 146         // Passing in a name registers this chart in the Chart namespace in the same way
 147         name: "LineAlt",
 148         initialize: function(data){
 149                 console.log('My Line chart extension');
 150                 Chart.types.Line.prototype.initialize.apply(this, arguments);
 151         }
 152 });
 153
 154 // Creates a line chart in the same way
 155 new Chart(ctx).LineAlt(data);
 156 // but this logs 'My Line chart extension' in the console.
 157 ```
 158
 159 ### Community extensions
 160
 161 - <a href="https://github.com/Regaddi/Chart.StackedBar.js" target="_blank">Stacked Bar Chart</a> by <a href="https://twitter.com/Regaddi" target="_blank">@Regaddi</a>
 162 - <a href="https://github.com/tannerlinsley/Chart.StackedArea.js" target="_blank">Stacked Bar Chart</a> by <a href="https://twitter.com/tannerlinsley" target="_blank">@tannerlinsley</a>
 163 - <a href="https://github.com/CAYdenberg/Chart.js" target="_blank">Error bars (bar and line charts)</a> by <a href="https://twitter.com/CAYdenberg" target="_blank">@CAYdenberg</a>
 164 - <a href="http://dima117.github.io/Chart.Scatter/" target="_blank">Scatter chart (number & date scales are supported)</a> by <a href="https://github.com/dima117" target="_blank">@dima117</a>
 165
 166 ### Creating custom builds
 167
 168 Chart.js uses <a href="http://gulpjs.com/" target="_blank">gulp</a> to build the library into a single JavaScript file. We can use this same build script with custom parameters in order to build a custom version.
 169
 170 Firstly, we need to ensure development dependencies are installed. With node and npm installed, after cloning the Chart.js repo to a local directory, and navigating to that directory in the command line, we can run the following:
 171
 172 ```bash
 173 npm install
 174 npm install -g gulp
 175 ```
 176
 177 This will install the local development dependencies for Chart.js, along with a CLI for the JavaScript task runner <a href="http://gulpjs.com/" target="_blank">gulp</a>.
 178
 179 Now, we can run the `gulp build` task, and pass in a comma-separated list of types as an argument to build a custom version of Chart.js with only specified chart types.
 180
 181 Here we will create a version of Chart.js with only Line, Radar and Bar charts included:
 182
 183 ```bash
 184 gulp build --types=Line,Radar,Bar
 185 ```
 186
 187 This will output to the `/custom` directory, and write two files, Chart.js, and Chart.min.js with only those chart types included.