Merge pull request #7092 from umbraco/cms/rte-tiptap-updates

Tiptap RTE updates for v15.4 and v16.0

Author: eshanrnh

15/umbraco-cms/SUMMARY.md

@@ -82,6 +82,7 @@
         * [Configuration](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/configuration.md)
         * [Extensions](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/extensions.md)
         * [Blocks](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/blocks.md)
+        * [Style Menu](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/style-menu.md)
         * [Change Rich Text Editor UI](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/change-rich-text-editor-ui.md)
       * [Rich Text Editor TinyMce](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor-tinymce/README.md)
         * [Configuration](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor-tinymce/configuration.md)

15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/README.md

@@ -21,6 +21,10 @@ The Rich Text Editor (RTE) Tiptap property editor is highly configurable and bas
 
 Customize everything from toolbar options to editor size to where pasted images are saved.
 
+## [Style Menu](style-menu.md)
+
+Define a cascading text formatting and style menu for the Rich Text Editor toolbar.
+
 ## [Blocks](blocks.md)
 
 Use Blocks to define specific parts that can be added as part of the markup of the Rich Text Editor.

15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/configuration.md

@@ -8,7 +8,7 @@ You have full control over which options should be available on the RTE.
 
 ![Toolbar: All options enabled](images/rte-tiptap-all-toolbar-items.png)
 
-In the example above, all 27 options have been enabled. These options include font styles like bold and italics, bullet lists, and options to embed videos and insert images.
+In the example above, all 38 options have been enabled. These options include font styles like bold and italics, bullet lists, and options to embed videos and insert images.
 
 You can customize the look of the toolbar:
 
@@ -17,6 +17,18 @@ You can customize the look of the toolbar:
 
 ![Enhance and customize the capabilities of the Rich Text Editor toolbar](images/rte-tiptap-capabilities-and-toolbar.png)
 
+## Statusbar
+
+As well as the toolbar, you can configure extensions for the statusbar.
+
+![Statusbar with Word Count extension enabled](images/rte-tiptap-statusbar.png)
+
+## Stylesheets
+
+To apply custom styles to the Rich Text Editor, you can select from any existing stylesheets.
+
+Stylesheets can be created in the **Settings** section. To learn more about this feature, see the [Stylesheets in the Backoffice](../../../../design/stylesheets-javascript.md) article.
+
 ## Dimensions
 
 Define `height` and `width` of the editor displayed in the content section.

15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-tiptap-all-toolbar-items.png

@@ -0,0 +1,114 @@
+# Style Menu
+
+A Style Menu is a configurable extension that adds a cascading menu to the toolbar for applying text styles and formatting.
+
+![Rich Text Editor cascading style menu](images/rte-tiptap-stylemenu.png)
+
+{% hint style="info" %}
+Any custom stylesheets associated with the Rich Text Editor will not auto generate a style menu in the toolbar.
+{% endhint %}
+
+### Creating a Style Menu
+
+In this article, you can find an example of how to set up a Style Menu using the package manifest file.
+
+{% code title="umbraco-package.json" %}
+```json
+{
+    "name": "Name of your package",
+    "alias": "My.Package",
+    "extensions": [
+        {
+            "type": "tiptapToolbarExtension",
+            "kind": "styleMenu",
+            "alias": "MyCustom.Tiptap.StyleMenu",
+            "name": "My Custom Tiptap Style Menu",
+            "meta": {
+                "alias": "myCustomStyleMenu",
+                "icon": "icon-palette",
+                "label": "My custom styles"
+            },
+            "items": [
+                {
+                    "label": "Headings",
+                    "items": [
+                        {
+                            "label": "Heading 2",
+                            "data": { "tag": "h2" },
+                            "appearance": { "icon": "icon-heading-2" }
+                        },
+                        {
+                            "label": "Heading 3",
+                            "data": { "tag": "h3" },
+                            "appearance": { "style": "font-size: large;" }
+                        },
+                        {
+                            "label": "Heading 4",
+                            "data": { "tag": "h4" }
+                        }
+                    ]
+                },
+                {
+                    "label": "Attributes",
+                    "items": [
+                        {
+                            "label": "Classes",
+                            "data": { "class": "foo" }
+                        },
+                        { 
+                            "label": "IDs",
+                            "data": { "id": "bar" }
+                        },
+                        {
+                            "label": "Mixed",
+                            "data": { "tag": "span", "class": "foo", "id": "bar" }
+                        }
+                    ]
+                }
+            ]
+        }
+    ]
+}
+```
+{% endcode %}
+
+
+The `items` property defines the structure of the style menu. Each menu item has the following options:
+
+- `label`: _(required)_ The label of the menu item. This supports localization keys.
+- `appearance`: This defines the appearance of the menu item. The value has 2 optional properties:
+  - `icon`: To prefix an icon to the menu item.
+  - `style`: To apply CSS rules to the menu item.
+- `data`: To configure the function of the style menu item. The value has 3 optional properties:
+  - `tag`: A [supported HTML tag](#supported-html-tags) name. This will be applied to the selected text.
+  - `class`: Applies a class attribute with the defined class name to the containing tag of the selected text.
+  - `id`: Applies an ID attribute with the defined ID value to the containing tag of the selected text.
+- `separatorAfter`: When `true`, it will add a line separator after the menu item.
+- `items`: To enable a cascading menu, an array of nested menu items may be added.
+
+
+Once configured, all custom style menus will appear in the Rich Text Editor toolbar options, as described in the [Rich Text Editor Configuration](configuration.md) article.
+
+
+#### Supported HTML tags
+
+Since the Tiptap has a strict rich-text schema, only supported HTML tags can be used in the style menu, _(arbitrary markup will be excluded)._ The following HTML tag names are supported: 
+
+- `h1`
+- `h2`
+- `h3`
+- `h4`
+- `h5`
+- `h6`
+-  `p`
+- `blockquote`
+- `code`
+- `codeBlock`
+- `div`
+- `em` (italic)
+- `ol`
+- `strong` (bold)
+- `s` (strike-through)
+- `span`
+- `u` (underline)
+- `ul`

15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-tiptap-capabilities-and-toolbar.png

@@ -81,6 +81,7 @@
         * [Configuration](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/configuration.md)
         * [Extensions](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/extensions.md)
         * [Blocks](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/blocks.md)
+        * [Style Menu](fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/style-menu.md)
   * [Login](fundamentals/backoffice/login.md)
   * [Document Blueprints](fundamentals/backoffice/document-blueprints.md)
   * [Sidebar](fundamentals/backoffice/sidebar.md)

15/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/images/rte-tiptap-statusbar.png

@@ -16,6 +16,10 @@ The Rich Text Editor property editor is highly configurable and based on [Tiptap
 
 Customize everything from toolbar options to editor size to where pasted images are saved.
 
+## [Style Menu](style-menu.md)
+
+Define a cascading text formatting and style menu for the Rich Text Editor toolbar.
+
 ## [Blocks](blocks.md)
 
 Use Blocks to define specific parts that can be added as part of the markup of the Rich Text Editor.