Add documentation for #12429

docs/links/grapesjs_api.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "grapesjs-api" 
+link_text = "GrapesJS API documentation" 
+link_url = "https://grapesjs.com/docs/api/" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/grapesjs_demo_plugin.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "GrapesJS Demo Plugin" 
+link_text = "demo GrapesJS Plugin" 
+link_url = "https://github.com/mautic/GrapesJsCustomPluginBundle" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/grapesjs_plugins.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "grapesjs-plugins" 
+link_text = "GrapesJS Plugins" 
+link_url = "https://grapesjs.com/docs/modules/Plugins.html" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/themes/grapesjs.rst

@@ -1,6 +1,9 @@
 GrapesJS Builder
 ################
 
+MJML
+****
+
 The GrapesJS Builder doesn't require any special HTML syntax to edit content in the Builder. However, for Emails, it supports the :xref:`MJML email framework` to create responsive emails.
 
 .. code-block:: html
@@ -38,4 +41,88 @@ The GrapesJS Builder doesn't require any special HTML syntax to edit content in
           </mj-column>
         </mj-section>
       </mj-body>
-    </mjml>
+    </mjml>
+
+GrapesJS Builder Plugins
+************************
+
+From Mautic 5.1 it's possible to create Plugins for the GrapesJS Builder. This allows you to add custom blocks, Components, and styles to the Builder. It's how the GrapesJS Preset works, which ships with Mautic.
+
+This uses the :xref:`grapesjs-plugins` feature. Read more about the potential this unlocks in the :xref:`grapesjs-api`.
+
+.. vale off
+
+Creating a Plugin for GrapesJS
+===============================
+
+.. vale on
+
+To create a Plugin for the GrapesJS Builder, you need to create a new Bundle in Mautic. This contains the Plugin and any other related code.
+
+1. Create a new Bundle in Mautic, for example ``GrapesJSCustomPluginBundle``.
+2. Create a GrapesJS Plugin - for example ``.Assets/src/index.ts`` - as follows. Note this uses TypeScript but vanilla JS also works:
+
+.. code-block:: typescript
+
+        import grapesjs from 'grapesjs';
+
+        // declare type for window so TS will not complain during compiling
+        declare global {
+            interface Window {
+                MauticGrapesJsPlugins: object[];
+            }
+        }
+
+        export type PluginOptions = {
+        };
+
+        export type RequiredPluginOptions = Required<PluginOptions>;
+
+        const GrapesJsCustomPlugin: grapesjs.Plugin<PluginOptions> = (editor, opts: Partial<PluginOptions> = {}) => {
+            const options: RequiredPluginOptions = {
+                ...opts
+            };
+            console.log('Run GrapesJsCustomPlugin...')
+            console.log('Options passed to GrapesJsCustomPlugin:', options)
+            editor.on('load', () => {
+                console.log('GrapesJsCustomPlugin: editor.onLoad()')
+            });
+        }
+
+        // export the plugin in case someone wants to use it as source module
+        export default GrapesJsCustomPlugin;
+
+        // create a global window-object which holds the information about GrapesJS plugins
+        if (!window.MauticGrapesJsPlugins) window.MauticGrapesJsPlugins = [];
+        // add the plugin-function with a name to the window-object
+        window.MauticGrapesJsPlugins.push({
+            name: 'GrapesJsCustomPlugin', // required
+            plugin: GrapesJsCustomPlugin, // required
+            context: ['page', 'email-mjml'], // optional. default is none/empty, so the plugin is always added; options: [page|email-mjml|email-html]
+            pluginOptions: { options: { test: true, hello: 'world'} } // optional
+        })
+
+Due to the ``export default``, you can use this Plugin in a fork, customizing the source files with ``import GrapesJSCustomPlugin from 'path'``. But this isn't required - you can also write a plain JS function as described in the :xref:`grapesjs-plugins` documentation.
+
+3. Add the JavaScript file - compiled or source - to the ``AssetSubscriber`` of your Plugin bundle:
+
+.. code-block:: php
+
+      public function injectAssets(CustomAssetsEvent $assetsEvent): void
+    {
+        if ($this->config->isPublished()) {
+            $assetsEvent->addScript('plugins/GrapesJsCustomPluginBundle/Assets/dist/index.js');
+        }
+    }
+
+The resulting HTML source appears as follows:
+
+.. code-block:: html
+
+  <script src="/plugins/GrapesJsCustomPluginBundle/Assets/dist/index.js?v6e9fccee" data-source="mautic"></script>
+  <script src="/plugins/GrapesJsBuilderBundle/Assets/library/js/dist/builder.js?v6e9fccee" data-source="mautic"></script>
+
+.. note:: 
+  The Plugin code loads before ``builder.js`` which results in the data registering in the global window object.
+
+You can download a :xref:`GrapesJS Demo Plugin` to get you started.