| commit | author | age | ||
| 83c3f6 | 1 | # Plugins |
| SP | 2 | |
| 3 | Plugins are the most efficient way to customize or change the default behavior of a chart. They have been introduced at [version 2.1.0](https://github.com/chartjs/Chart.js/releases/tag/2.1.0) (global plugins only) and extended at [version 2.5.0](https://github.com/chartjs/Chart.js/releases/tag/v2.5.0) (per chart plugins and options). | |
| 4 | ||
| 5 | ## Using plugins | |
| 6 | ||
| 7 | Plugins can be shared between chart instances: | |
| 8 | ||
| 9 | ```javascript | |
| 10 | var plugin = { /* plugin implementation */ }; | |
| 11 | ||
| 12 | // chart1 and chart2 use "plugin" | |
| 13 | var chart1 = new Chart(ctx, { | |
| 14 | plugins: [plugin] | |
| 15 | }); | |
| 16 | ||
| 17 | var chart2 = new Chart(ctx, { | |
| 18 | plugins: [plugin] | |
| 19 | }); | |
| 20 | ||
| 21 | // chart3 doesn't use "plugin" | |
| 22 | var chart3 = new Chart(ctx, {}); | |
| 23 | ``` | |
| 24 | ||
| 25 | Plugins can also be defined directly in the chart `plugins` config (a.k.a. *inline plugins*): | |
| 26 | ||
| 27 | ```javascript | |
| 28 | var chart = new Chart(ctx, { | |
| 29 | plugins: [{ | |
| 30 | beforeInit: function(chart, options) { | |
| 31 | //.. | |
| 32 | } | |
| 33 | }] | |
| 34 | }); | |
| 35 | ``` | |
| 36 | ||
| 37 | However, this approach is not ideal when the customization needs to apply to many charts. | |
| 38 | ||
| 39 | ## Global plugins | |
| 40 | ||
| 41 | Plugins can be registered globally to be applied on all charts (a.k.a. *global plugins*): | |
| 42 | ||
| 43 | ```javascript | |
| 44 | Chart.plugins.register({ | |
| 45 | // plugin implementation | |
| 46 | }); | |
| 47 | ``` | |
| 48 | ||
| 49 | > Note: *inline* plugins can't be registered globally. | |
| 50 | ||
| 51 | ## Configuration | |
| 52 | ||
| 53 | ### Plugin ID | |
| 54 | ||
| 55 | Plugins must define a unique id in order to be configurable. | |
| 56 | ||
| 57 | This id should follow the [npm package name convention](https://docs.npmjs.com/files/package.json#name): | |
| 58 | ||
| 59 | - can't start with a dot or an underscore | |
| 60 | - can't contain any non-URL-safe characters | |
| 61 | - can't contain uppercase letters | |
| 62 | - should be something short, but also reasonably descriptive | |
| 63 | ||
| 64 | If a plugin is intended to be released publicly, you may want to check the [registry](https://www.npmjs.com/search?q=chartjs-plugin-) to see if there's something by that name already. Note that in this case, the package name should be prefixed by `chartjs-plugin-` to appear in Chart.js plugin registry. | |
| 65 | ||
| 66 | ### Plugin options | |
| 67 | ||
| 68 | Plugin options are located under the `options.plugins` config and are scoped by the plugin ID: `options.plugins.{plugin-id}`. | |
| 69 | ||
| 70 | ```javascript | |
| 71 | var chart = new Chart(ctx, { | |
| 72 | config: { | |
| 73 | foo: { ... }, // chart 'foo' option | |
| 74 | plugins: { | |
| 75 | p1: { | |
| 76 | foo: { ... }, // p1 plugin 'foo' option | |
| 77 | bar: { ... } | |
| 78 | }, | |
| 79 | p2: { | |
| 80 | foo: { ... }, // p2 plugin 'foo' option | |
| 81 | bla: { ... } | |
| 82 | } | |
| 83 | } | |
| 84 | } | |
| 85 | }); | |
| 86 | ``` | |
| 87 | ||
| 88 | #### Disable plugins | |
| 89 | ||
| 90 | To disable a global plugin for a specific chart instance, the plugin options must be set to `false`: | |
| 91 | ||
| 92 | ```javascript | |
| 93 | Chart.plugins.register({ | |
| 94 | id: 'p1', | |
| 95 | // ... | |
| 96 | }); | |
| 97 | ||
| 98 | var chart = new Chart(ctx, { | |
| 99 | config: { | |
| 100 | plugins: { | |
| 101 | p1: false // disable plugin 'p1' for this instance | |
| 102 | } | |
| 103 | } | |
| 104 | }); | |
| 105 | ``` | |
| 106 | ||
| 107 | ## Plugin Core API | |
| 108 | ||
| 109 | Available hooks (as of version 2.6): | |
| 110 | ||
| 111 | * beforeInit | |
| 112 | * afterInit | |
| 113 | * beforeUpdate *(cancellable)* | |
| 114 | * afterUpdate | |
| 115 | * beforeLayout *(cancellable)* | |
| 116 | * afterLayout | |
| 117 | * beforeDatasetsUpdate *(cancellable)* | |
| 118 | * afterDatasetsUpdate | |
| 119 | * beforeDatasetUpdate *(cancellable)* | |
| 120 | * afterDatasetUpdate | |
| 121 | * beforeRender *(cancellable)* | |
| 122 | * afterRender | |
| 123 | * beforeDraw *(cancellable)* | |
| 124 | * afterDraw | |
| 125 | * beforeDatasetsDraw *(cancellable)* | |
| 126 | * afterDatasetsDraw | |
| 127 | * beforeDatasetDraw *(cancellable)* | |
| 128 | * afterDatasetDraw | |
| 129 | * beforeEvent *(cancellable)* | |
| 130 | * afterEvent | |
| 131 | * resize | |
| 132 | * destroy | |
