From 5a88c169b5395aeade7c89e3eee8fd2c5bd68896 Mon Sep 17 00:00:00 2001 From: Ruth Cheesley Date: Tue, 23 Apr 2024 10:00:30 +0100 Subject: [PATCH 1/2] Add content --- docs/links/grapesjs_api.py | 7 +++ docs/links/grapesjs_demo_plugin.py | 7 +++ docs/links/grapesjs_plugins.py | 7 +++ docs/themes/grapesjs.rst | 89 +++++++++++++++++++++++++++++- 4 files changed, 109 insertions(+), 1 deletion(-) create mode 100644 docs/links/grapesjs_api.py create mode 100644 docs/links/grapesjs_demo_plugin.py create mode 100644 docs/links/grapesjs_plugins.py diff --git a/docs/links/grapesjs_api.py b/docs/links/grapesjs_api.py new file mode 100644 index 00000000..87ffcfb6 --- /dev/null +++ b/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)}) diff --git a/docs/links/grapesjs_demo_plugin.py b/docs/links/grapesjs_demo_plugin.py new file mode 100644 index 00000000..dcd01c16 --- /dev/null +++ b/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)}) diff --git a/docs/links/grapesjs_plugins.py b/docs/links/grapesjs_plugins.py new file mode 100644 index 00000000..014dc824 --- /dev/null +++ b/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)}) diff --git a/docs/themes/grapesjs.rst b/docs/themes/grapesjs.rst index 09f06cdc..da1eb35d 100644 --- a/docs/themes/grapesjs.rst +++ b/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 - \ No newline at end of file + + +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; + + const GrapesJsCustomPlugin: grapesjs.Plugin = (editor, opts: Partial = {}) => { + 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 + + + + +.. 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. \ No newline at end of file From f01fccad7556c7ff0c572bea0fd025c9b200e183 Mon Sep 17 00:00:00 2001 From: Ruth Cheesley Date: Tue, 23 Apr 2024 10:31:58 +0100 Subject: [PATCH 2/2] Vale fixes :blush: --- docs/themes/grapesjs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/themes/grapesjs.rst b/docs/themes/grapesjs.rst index da1eb35d..5e7024e5 100644 --- a/docs/themes/grapesjs.rst +++ b/docs/themes/grapesjs.rst @@ -104,7 +104,7 @@ To create a Plugin for the GrapesJS Builder, you need to create a new Bundle in 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: +3. Add the JavaScript file - compiled or source - to the ``AssetSubscriber`` of your Plugin bundle: .. code-block:: php