From e7827aafb55711d3ce7ac17abaccd0c44f253b4f Mon Sep 17 00:00:00 2001 From: Guy Sartorelli Date: Thu, 18 Apr 2024 15:21:06 +1200 Subject: [PATCH] DOC Document TinyMCE changes --- .../Field_types/03_HTMLEditorField.md | 2 ++ en/08_Changelogs/5.3.0.md | 23 +++++++++++++++++++ 2 files changed, 25 insertions(+) diff --git a/en/02_Developer_Guides/03_Forms/Field_types/03_HTMLEditorField.md b/en/02_Developer_Guides/03_Forms/Field_types/03_HTMLEditorField.md index 76e225cc4..8ac526c33 100644 --- a/en/02_Developer_Guides/03_Forms/Field_types/03_HTMLEditorField.md +++ b/en/02_Developer_Guides/03_Forms/Field_types/03_HTMLEditorField.md @@ -142,6 +142,8 @@ TinyMCEConfig::get('cms')->removeButtons('tablecontrols', 'blockquote', 'hr'); TinyMCE behaviour can be affected through its [configuration options](https://www.tiny.cloud/docs/tinymce/6/basic-setup). These options will be passed straight to the editor. +A default set of options has been defined in the [`TinyMCEConfig.default_options`](api:SilverStripe\Forms\HTMLEditor\TinyMCEConfig->default_options) configuration property. + One example of the usage of this capability is to redefine the TinyMCE's [whitelist of HTML tags](https://www.tiny.cloud/docs/tinymce/6/content-filtering/#extended_valid_elements) - the tags that will not be stripped from the HTML source by the editor. diff --git a/en/08_Changelogs/5.3.0.md b/en/08_Changelogs/5.3.0.md index 814412c82..3bc90c07c 100644 --- a/en/08_Changelogs/5.3.0.md +++ b/en/08_Changelogs/5.3.0.md @@ -14,6 +14,21 @@ title: 5.3.0 (unreleased) ## Features and enhancements +### Changes to `TinyMCEConfig` {#changes-to-tinymce} + +In order to facilitate fixing a bug related to the sanitisation of HTML content via the [`HTMLEditorSanitiser`](api:SilverStripe\Forms\HTMLEditor\HTMLEditorSanitiser) class, some changes had to be made to the [`TinyMCEConfig`](api:SilverStripe\Forms\HTMLEditor\TinyMCEConfig) class. Those changes are as follows: + +- If `valid_elements` and `extended_valid_elements` are both empty, all HTML elements will be stripped out of the HTML content. +- A default set of `valid_elements` has been defined for all `TinyMCEConfig` instances. If you use custom `TinyMCEConfig` definitions and have not explicitly set the `valid_elements` option, you may have more elements permitted than you were expecting. +- There is a new [`TinyMCEConfig.default_options`](api:SilverStripe\Forms\HTMLEditor\TinyMCEConfig->default_options) configuration property which allows you to define the default options for all `TinyMCEConfig` instances. + +> [!WARNING] +> If you use custom `TinyMCEConfig` definitions, we strongly recommend double checking if they include a definition of `valid_elements`, and if they don't, validate whether the default set defined in `TinyMCEConfig.default_options` is suitable for you. +> +> You can either change the `TinyMCEConfig.default_options` configuration value to affect the options for all `TinyMCEConfig` definitions, or explicitly define `valid_elements` for your specific configuration instances. See [setting options](/developer_guides/forms/field_types/htmleditorfield/#setting-options) for more details. + +See [sanitisation of HTML](#sanitisation-of-html) for more information about the bug that was fixed. + ### High-level API for converting files {#file-converter} There is now a high-level API for converting files from one format to another. This builds on top of the low-level API which was [added in 5.2.0](/changelogs/5.2.0/#file-variants). @@ -49,6 +64,14 @@ This is particularly helpful if you need to update columns in one table to match This release includes a number of bug fixes to improve a broad range of areas. Check the change logs for full details of these fixes split by module. Thank you to the community members that helped contribute these fixes as part of the release! +### Sanitisation of HTML + +When you save content in a `HTMLEditorField`, the [`HTMLEditorSanitiser`](api:SilverStripe\Forms\HTMLEditor\HTMLEditorSanitiser) class is responsible for ensuring the HTML content is safe and matches the `valid_elements` and `extended_valid_elements` options you've defined. + +There was a bug that resulted in `HTMLEditorSanitiser` using the 'active' `HTMLEditorConfig` instance rather than the instance which was defined for the field. In many cases this goes unnoticed because the default active instance is very permissive, and TinyMCE does a lot of this work on the client-side, but it was possible to bypass the defined allowed HTML elements by sending requests directly to the server. + +This bug has been fixed, but some additional changes were required to facilitate it. See [changes to `TinyMCEConfig`](#changes-to-tinymce) for more details about those changes. +