Sample plugin in docs for canvas background (#8492)

* color done

* add example inline plugins for background image and color

* add link to css background

* improve text bit

* fix build error

* implement kurkles feedback

* fix indenting tab -> spaces

diff --git a/docs/docs/configuration/canvas-background.mdx b/docs/docs/configuration/canvas-background.mdx
new file mode 100644 (file)
index 0000000..673e487
--- /dev/null
+++ b/docs/docs/configuration/canvas-background.mdx
@@ -0,0 +1,117 @@
+---
+title: Canvas background
+---
+
+In some use cases you would want a background image or color over the whole canvas. There is no build in support for this, the way you can achieve this is by writing a custom plugin.
+
+In the two example plugins underneath here you can see how you can draw an color or image to the canvas as background. This way of giving the chart a background is only necessary if you want to export the chart with that specific background.
+For normal use you can set the background more easily with [CSS](https://www.w3schools.com/cssref/css3_pr_background.asp).
+
+import { useEffect, useRef } from 'react';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs
+    defaultValue='color'
+    values={[
+        {label: 'Color', value: 'color' },
+        {label: 'Image', value: 'image' },
+    ]}
+>
+<TabItem value="color">
+
+```jsx live
+function example() {
+  const canvas = useRef(null);
+  useEffect(() => {
+    const cfg = {
+      type: 'doughnut',
+      data: {
+        labels: [
+          'Red',
+          'Blue',
+          'Yellow'
+        ],
+        datasets: [{
+          label: 'My First Dataset',
+          data: [300, 50, 100],
+          backgroundColor: [
+            'rgb(255, 99, 132)',
+            'rgb(54, 162, 235)',
+            'rgb(255, 205, 86)'
+          ],
+          hoverOffset: 4
+        }]
+      },
+      plugins: [{
+        id: 'custom_canvas_background_color',
+        beforeDraw: (chart) => {
+          const ctx = chart.canvas.getContext('2d');
+          ctx.save();
+          ctx.globalCompositeOperation = 'destination-over';
+          ctx.fillStyle = 'lightGreen';
+          ctx.fillRect(0, 0, chart.canvas.width, chart.canvas.height);
+          ctx.restore();
+        }
+      }]
+    };
+    const chart = new Chart(canvas.current.getContext('2d'), cfg);
+    return () => chart.destroy();
+  });
+  return <div className="chartjs-wrapper"><canvas ref={canvas} className="chartjs"></canvas></div>;
+}
+```
+
+</TabItem>
+
+<TabItem value="image">
+
+```jsx live
+function example() {
+  const canvas = useRef(null);
+
+  useEffect(() => {
+    const image = new Image();
+    image.src = "https://www.chartjs.org/img/chartjs-logo.svg";
+
+    const cfg = {
+      type: 'doughnut',
+      data: {
+        labels: [
+          'Red',
+          'Blue',
+          'Yellow'
+        ],
+        datasets: [{
+          label: 'My First Dataset',
+          data: [300, 50, 100],
+          backgroundColor: [
+            'rgb(255, 99, 132)',
+            'rgb(54, 162, 235)',
+            'rgb(255, 205, 86)'
+          ],
+          hoverOffset: 4
+        }]
+      },
+      plugins: [{
+        id: 'custom_canvas_background_image',
+        beforeDraw: (chart) => {
+          if (image.complete) {
+            const ctx = chart.canvas.getContext('2d');
+            ctx.drawImage(image, chart.canvas.width/2-image.width/2, chart.canvas.height/2-image.height/2);
+          }
+        }
+      }]
+    };
+
+    const chart = new Chart(canvas.current.getContext('2d'), cfg);
+    image.onload = () => chart.draw();
+
+    return () => chart.destroy();
+  });
+  return <div className="chartjs-wrapper"><canvas ref={canvas} className="chartjs"></canvas></div>;
+}
+```
+
+</TabItem>
+</Tabs>

diff --git a/docs/sidebars.js b/docs/sidebars.js
index 8dd60572cbca956537777e9d3a80662172e2cd9b..dbdf2ed0a441e71843e56bfd86ce58d6ba17c02e 100644 (file)
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -25,6 +25,7 @@ module.exports = {
       'configuration/device-pixel-ratio',
       'configuration/locale',
       {Interactions: ['configuration/interactions/index', 'configuration/interactions/events', 'configuration/interactions/modes']},
+      'configuration/canvas-background',
       'configuration/animations',
       'configuration/layout',
       'configuration/legend',