| commit | author | age | ||
| 83c3f6 | 1 | # New Axes |
| SP | 2 | |
| 3 | Axes in Chart.js can be individually extended. Axes should always derive from Chart.Scale but this is not a mandatory requirement. | |
| 4 | ||
| 5 | ```javascript | |
| 6 | let MyScale = Chart.Scale.extend({ | |
| 7 | /* extensions ... */ | |
| 8 | }); | |
| 9 | ||
| 10 | // MyScale is now derived from Chart.Scale | |
| 11 | ``` | |
| 12 | ||
| 13 | Once you have created your scale class, you need to register it with the global chart object so that it can be used. A default config for the scale may be provided when registering the constructor. The first parameter to the register function is a string key that is used later to identify which scale type to use for a chart. | |
| 14 | ||
| 15 | ```javascript | |
| 16 | Chart.scaleService.registerScaleType('myScale', MyScale, defaultConfigObject); | |
| 17 | ``` | |
| 18 | ||
| 19 | To use the new scale, simply pass in the string key to the config when creating a chart. | |
| 20 | ||
| 21 | ```javascript | |
| 22 | var lineChart = new Chart(ctx, { | |
| 23 | data: data, | |
| 24 | type: 'line', | |
| 25 | options: { | |
| 26 | scales: { | |
| 27 | yAxes: [{ | |
| 28 | type: 'myScale' // this is the same key that was passed to the registerScaleType function | |
| 29 | }] | |
| 30 | } | |
| 31 | } | |
| 32 | }) | |
| 33 | ``` | |
| 34 | ||
| 35 | ## Scale Properties | |
| 36 | ||
| 37 | Scale instances are given the following properties during the fitting process. | |
| 38 | ||
| 39 | ```javascript | |
| 40 | { | |
| 41 | left: Number, // left edge of the scale bounding box | |
| 42 | right: Number, // right edge of the bounding box' | |
| 43 | top: Number, | |
| 44 | bottom: Number, | |
| 45 | width: Number, // the same as right - left | |
| 46 | height: Number, // the same as bottom - top | |
| 47 | ||
| 48 | // Margin on each side. Like css, this is outside the bounding box. | |
| 49 | margins: { | |
| 50 | left: Number, | |
| 51 | right: Number, | |
| 52 | top: Number, | |
| 53 | bottom: Number, | |
| 54 | }, | |
| 55 | ||
| 56 | // Amount of padding on the inside of the bounding box (like CSS) | |
| 57 | paddingLeft: Number, | |
| 58 | paddingRight: Number, | |
| 59 | paddingTop: Number, | |
| 60 | paddingBottom: Number, | |
| 61 | } | |
| 62 | ``` | |
| 63 | ||
| 64 | ## Scale Interface | |
| 65 | To work with Chart.js, custom scale types must implement the following interface. | |
| 66 | ||
| 67 | ```javascript | |
| 68 | { | |
| 69 | // Determines the data limits. Should set this.min and this.max to be the data max/min | |
| 70 | determineDataLimits: function() {}, | |
| 71 | ||
| 72 | // Generate tick marks. this.chart is the chart instance. The data object can be accessed as this.chart.data | |
| 73 | // buildTicks() should create a ticks array on the axis instance, if you intend to use any of the implementations from the base class | |
| 74 | buildTicks: function() {}, | |
| 75 | ||
| 76 | // Get the value to show for the data at the given index of the the given dataset, ie this.chart.data.datasets[datasetIndex].data[index] | |
| 77 | getLabelForIndex: function(index, datasetIndex) {}, | |
| 78 | ||
| 79 | // Get the pixel (x coordinate for horizontal axis, y coordinate for vertical axis) for a given value | |
| 80 | // @param index: index into the ticks array | |
| 81 | // @param includeOffset: if true, get the pixel halfway between the given tick and the next | |
| 82 | getPixelForTick: function(index, includeOffset) {}, | |
| 83 | ||
| 84 | // Get the pixel (x coordinate for horizontal axis, y coordinate for vertical axis) for a given value | |
| 85 | // @param value : the value to get the pixel for | |
| 86 | // @param index : index into the data array of the value | |
| 87 | // @param datasetIndex : index of the dataset the value comes from | |
| 88 | // @param includeOffset : if true, get the pixel halfway between the given tick and the next | |
| 89 | getPixelForValue: function(value, index, datasetIndex, includeOffset) {} | |
| 90 | ||
| 91 | // Get the value for a given pixel (x coordinate for horizontal axis, y coordinate for vertical axis) | |
| 92 | // @param pixel : pixel value | |
| 93 | getValueForPixel: function(pixel) {} | |
| 94 | } | |
| 95 | ``` | |
| 96 | ||
| 97 | Optionally, the following methods may also be overwritten, but an implementation is already provided by the `Chart.Scale` base class. | |
| 98 | ||
| 99 | ```javascript | |
| 100 | // Transform the ticks array of the scale instance into strings. The default implementation simply calls this.options.ticks.callback(numericalTick, index, ticks); | |
| 101 | convertTicksToLabels: function() {}, | |
| 102 | ||
| 103 | // Determine how much the labels will rotate by. The default implementation will only rotate labels if the scale is horizontal. | |
| 104 | calculateTickRotation: function() {}, | |
| 105 | ||
| 106 | // Fits the scale into the canvas. | |
| 107 | // this.maxWidth and this.maxHeight will tell you the maximum dimensions the scale instance can be. Scales should endeavour to be as efficient as possible with canvas space. | |
| 108 | // this.margins is the amount of space you have on either side of your scale that you may expand in to. This is used already for calculating the best label rotation | |
| 109 | // You must set this.minSize to be the size of your scale. It must be an object containing 2 properties: width and height. | |
| 110 | // You must set this.width to be the width and this.height to be the height of the scale | |
| 111 | fit: function() {}, | |
| 112 | ||
| 113 | // Draws the scale onto the canvas. this.(left|right|top|bottom) will have been populated to tell you the area on the canvas to draw in | |
| 114 | // @param chartArea : an object containing four properties: left, right, top, bottom. This is the rectangle that lines, bars, etc will be drawn in. It may be used, for example, to draw grid lines. | |
| 115 | draw: function(chartArea) {}, | |
| 116 | ``` | |
| 117 | ||
| 118 | The Core.Scale base class also has some utility functions that you may find useful. | |
| 119 | ```javascript | |
| 120 | { | |
| 121 | // Returns true if the scale instance is horizontal | |
| 122 | isHorizontal: function() {}, | |
| 123 | ||
| 124 | // Get the correct value from the value from this.chart.data.datasets[x].data[] | |
| 125 | // If dataValue is an object, returns .x or .y depending on the return of isHorizontal() | |
| 126 | // If the value is undefined, returns NaN | |
| 127 | // Otherwise returns the value. | |
| 128 | // Note that in all cases, the returned value is not guaranteed to be a Number | |
| 129 | getRightValue: function(dataValue) {}, | |
| 130 | } | |
| 131 | ``` | |
