From b264b44650a98549570b11820a6254df2b002449 Mon Sep 17 00:00:00 2001
From: Peter Mathis <petschki@users.noreply.github.com>
Date: Fri, 6 Dec 2024 12:45:40 +0100
Subject: [PATCH] Continue tinymce customization docs (#1808)

* Continue tinymce customization docs

* Add GenericSetup example to remove menu items, and split into subsections

* Improve flow of narrative and sprinkle some MyST to make it pretty

---------

Co-authored-by: Steve Piercy <web@stevepiercy.com>
---
 docs/classic-ui/tinymce-customization.md | 57 +++++++++++++++++++++++-
 1 file changed, 55 insertions(+), 2 deletions(-)

diff --git a/docs/classic-ui/tinymce-customization.md b/docs/classic-ui/tinymce-customization.md
index eeb3bdcb3..5f5032063 100644
--- a/docs/classic-ui/tinymce-customization.md
+++ b/docs/classic-ui/tinymce-customization.md
@@ -26,7 +26,7 @@ They are less complicated to implement than the third option.
 
 This option is best for system administrators and developers who write their own add-ons to ease reproducibility.
 
-You can add a GenericSetup configuration file to your add-on, such as {file}`profiles/default/registry/tinymce.xml`, with the following content.
+You can add a GenericSetup configuration file to your add-on, such as {file}`profiles/default/registry/tinymce.xml`, with the JSON configuration of the custom format.
 
 ```xml
 <registry>
@@ -44,6 +44,37 @@ You can add a GenericSetup configuration file to your add-on, such as {file}`pro
 </registry>
 ```
 
+```{important}
+The content of the `formats` record will overwrite the value in the {guilabel}`Formats` field in the TinyMCE control panel at {menuselection}`Site Setup --> TinyMCE --> Default`.
+If you want to preserve the default content, you must copy it into your XML.
+```
+
+Next, define where to place the new format inside the {menuselection}`Format` menu's submenus.
+You can add your custom format to one of the following menu items.
+These menu items in the TinyMCE editor correspond to field items in the TinyMCE control panel at {menuselection}`Site Setup --> TinyMCE --> Default`.
+
+(tinymce-formats-styles-label)=
+
+-   {guilabel}`Header styles`
+-   {guilabel}`Inline styles`
+-   {guilabel}`Block styles`
+-   {guilabel}`Alignment styles`
+-   {guilabel}`Table styles`
+
+The syntax for each element in those fields is `Title|format`.
+The following example XML snippet adds your format to the {menuselection}`Inline styles` menu.
+Unlike the previous example, the example does not remove the default values, but appends to it.
+
+```xml
+<record field="inline_styles"
+        interface="plone.base.interfaces.controlpanel.ITinyMCESchema"
+        name="plone.inline_styles">
+  <value>
+    <element>My custom format|myformat</element>
+  </value>
+</record>
+```
+
 
 ### Edit the `Formats` option in the TinyMCE control panel
 
@@ -53,13 +84,14 @@ You can manually customize the `Formats` value through-the-web in the TinyMCE co
 
 1.  Navigate to {menuselection}`Site Setup --> TinyMCE --> Default`, or append `@@tinymce-controlpanel` to the root of your website in your browser's location bar.
 1.  Scroll down to {guilabel}`Formats`, and edit the JSON configuration.
+1.  Insert your custom format to one of the fields mentioned above.
 1.  Click the {guilabel}`Save` button.
 
 
-
 ### Inject formats with files named {file}`tinymce-formats.css`
 
 This option is more complex to implement than the previous options.
+However it is the only option where you can add items to the {menuselection}`Formats` submenu as siblings to the {ref}`Formats styles <tinymce-formats-styles-label>` configurations.
 
 In Plone 6, TinyMCE has a special logic that automatically reads registered files named {file}`tinymce-formats.css` and adds the CSS classes defined in those files to TinyMCE's {menuselection}`Format --> Formats` menu by using the [`importcss_file_filter` option](https://www.tiny.cloud/docs/tinymce/latest/importcss/#importcss_file_filter).
 
@@ -76,6 +108,27 @@ CSS styles defined in this file will automatically be added to the top level of
 
 ## Remove imported formats
 
+Similar to adding formats, you can remove formats in a couple of ways.
+
+
+### Add-on GenericSetup configuration file
+
+Alternatively, you can use GenericSetup in your add-on.
+
+```xml
+<record field="content_css"
+          interface="plone.base.interfaces.controlpanel.ITinyMCESchema"
+          name="plone.content_css"
+  >
+    <value purge="true">
+      <element>++theme++barceloneta/tinymce/tinymce-ui-content.css</element>
+    </value>
+  </record>
+```
+
+
+### Configure the TinyMCE control panel
+
 Plone 6 Classic UI ships with the Barceloneta theme which includes two custom formats, `highlight-inline` and `p.highlight-paragraph`, in the TinyMCE {menuselection}`Format --> Formats` menu.
 You can remove these formats through the TinyMCE control panel.