From c80cc2206f0bf9c62ba6f8ddb5508306b3545954 Mon Sep 17 00:00:00 2001 From: Guy Sartorelli Date: Tue, 27 Sep 2022 17:32:39 +1300 Subject: [PATCH] DOC Document upgrading to tinymce 6 --- .../Field_types/03_HTMLEditorField.md | 54 +++++++++++-------- .../05_Typography.md | 23 +++++--- en/04_Changelogs/5.0.0.md | 24 +++++++++ 3 files changed, 71 insertions(+), 30 deletions(-) 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 373da7403..99632f4c7 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 @@ -7,7 +7,7 @@ icon: file-code # Rich-text editing (WYSIWYG) Editing and formatting content is the bread and butter of every content management system, which is why Silverstripe CMS -has a tight integration with our preferred editor library, [TinyMCE](http://tinymce.com). +has a tight integration with our preferred editor library, [TinyMCE](https://www.tiny.cloud/docs/tinymce/6/). On top of the base functionality, we use our own insertion dialogs to ensure you can effectively select and upload files. In addition to the markup managed by TinyMCE, we use [shortcodes](/developer_guides/extending/shortcodes) to store @@ -107,13 +107,12 @@ transparently generate the relevant underlying TinyMCE code. ```php use SilverStripe\Forms\HTMLEditor\HtmlEditorConfig; -HtmlEditorConfig::get('cms')->enablePlugins('media'); +HtmlEditorConfig::get('cms')->enablePlugins('emoticons'); ``` [notice] -This utilities the TinyMCE's `PluginManager::load` function under the hood (check the -[TinyMCE documentation on plugin loading](http://www.tinymce.com/wiki.php/API3:method.tinymce.AddOnManager.load) for -details). +This utilities the TinyMCE's [external_plugins](https://www.tiny.cloud/docs/tinymce/6/editor-important-options/#external_plugins) +option under the hood. [/notice] Plugins and advanced themes can provide additional buttons that can be added (or removed) through the @@ -134,29 +133,29 @@ HtmlEditorConfig::get('cms')->removeButtons('tablecontrols', 'blockquote', 'hr') ``` [notice] -Internally [HtmlEditorConfig](api:SilverStripe\Forms\HTMLEditor\HtmlEditorConfig) uses the TinyMCE's `theme_advanced_buttons` option to configure these. See the -[TinyMCE documentation of this option](http://www.tinymce.com/wiki.php/Configuration:theme_advanced_buttons_1_n) +Internally [HtmlEditorConfig](api:SilverStripe\Forms\HTMLEditor\HtmlEditorConfig) uses the TinyMCE's `toolbar` option to configure these. See the +[TinyMCE documentation of this option](https://www.tiny.cloud/docs/tinymce/6/toolbar-configuration-options/#toolbar) for more details. [/notice] ### Setting options -TinyMCE behaviour can be affected through its [configuration options](http://www.tinymce.com/wiki.php/Configuration). +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. One example of the usage of this capability is to redefine the TinyMCE's [whitelist of HTML -tags](http://www.tinymce.com/wiki.php/Configuration:extended_valid_elements) - the tags that will not be stripped +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. **app/_config.php** ```php -// Add start and type attributes for
    , add and with all attributes. +// Add start and type attributes for
      , add with all attributes. HtmlEditorConfig::get('cms')->setOption( 'extended_valid_elements', - 'img[class|src|alt|title|hspace|vspace|width|height|align|onmouseover|onmouseout|name|usemap],' . - 'iframe[src|name|width|height|title|align|allowfullscreen|frameborder|marginwidth|marginheight|scrolling],' . - 'object[classid|codebase|width|height|data|type],' . + 'img[class|src|alt|title|hspace|vspace|width|height|align|name|usemap|data*],' . + 'iframe[src|name|width|height|align|frameborder|marginwidth|marginheight|scrolling],' . + 'object[width|height|data|type],' . 'embed[src|type|pluginspage|width|height|autoplay],' . 'param[name|value],' . 'map[class|name|id],' . @@ -165,6 +164,19 @@ HtmlEditorConfig::get('cms')->setOption( ); ``` +Note that the `setOption()` _overrides_ any existing value for that option. If you only want to change some small part +of the existing option value, you can call `getOption()`, modify the returned value, and then pass the result to `setOption()`. + +```php +// Add start and type attributes for
        , add with all attributes - without redeclaring everything else +$editor = HtmlEditorConfig::get('cms'); +$validElements = $editor->getOption('extended_valid_elements') . ',' . + 'embed[src|type|pluginspage|width|height|autoplay],' . + 'ol[start|type]'; +$validElements = str_replace('iframe[', 'iframe[data-*|'); +$editor->setOption( 'extended_valid_elements', $validElements); +``` + [notice] The default setting for the CMS's `extended_valid_elements` we are overriding here can be found in `vendor/silverstripe/admin/_config.php`. @@ -181,7 +193,7 @@ You can enable them through [HtmlEditorConfig::enablePlugins()](api:SilverStripe HtmlEditorConfig::get('cms')->enablePlugins(['myplugin' => '../../../app/javascript/myplugin/editor_plugin.js']); ``` -You can learn how to [create a plugin](http://www.tinymce.com/wiki.php/Creating_a_plugin) from the TinyMCE documentation. +You can learn how to [create a plugin](https://www.tiny.cloud/docs/tinymce/6/creating-a-plugin/) from the TinyMCE documentation. ## Image and media insertion @@ -237,9 +249,6 @@ HtmlEditorConfig::get('cms')->setOption('image_size_presets', [ ]); ``` - - - ## oEmbed: Embedding media through external services The ["oEmbed" standard](http://www.oembed.com/) is implemented by many media services around the web, allowing easy @@ -317,17 +326,16 @@ point to localhost to protect your site from cross site request forgery. ### Doctypes Since TinyMCE generates markup, it needs to know which doctype your documents will be rendered in. You can set this -through the [element_format](http://www.tinymce.com/wiki.php/Configuration:element_format) configuration variable. It -defaults to the stricter 'xhtml' setting, for example rendering self closing tags like `
        ` instead of `
        `. - -In case you want to adhere to HTML4 instead, use the following configuration: +through the [element_format](https://www.tiny.cloud/docs/tinymce/6/content-filtering/#element_format) configuration variable. +In case you want to adhere to the stricter xhtml format (for example rendering self closing tags like `
        ` instead of `
        `), +use the following configuration: ```php -HtmlEditorConfig::get('cms')->setOption('element_format', 'html'); +HtmlEditorConfig::get('cms')->setOption('element_format', 'xhtml'); ``` -By default, TinyMCE and Silverstripe CMS will generate valid HTML5 markup, but it will strip out HTML5 tags like +By default, TinyMCE and Silverstripe CMS will generate valid HTML5 markup, but it will strip out many HTML5 tags like `
        ` or `
        `. If you plan to use those, add them to the [valid_elements](http://www.tinymce.com/wiki.php/Configuration:valid_elements) configuration setting. diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/05_Typography.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/05_Typography.md index 2242c6f8d..99747523c 100644 --- a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/05_Typography.md +++ b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/05_Typography.md @@ -27,16 +27,24 @@ $config = new TinyMCEConfig(); $config->setContentCSS([ '/app/client/css/editor.css' ]); ``` +[notice] +`silverstripe/admin` adds a small css file to `editor_css` which highlights broken links - you'll +probably want to include that in the array you pass to `setContentCSS()`, either by first calling +`getContentCSS()` and merging that array with your new one (and passing the result to `setContentCSS()`) +or by adding `'/_resources/vendor/silverstripe/admin/client/dist/styles/editor.css'` to the array you pass +to `setContentCSS()` +[/notice] + ## Custom style dropdown -The custom style dropdown can be enabled via the `importcss` plugin bundled with admin module. ([Doc](https://www.tinymce.com/docs/plugins/importcss/)) +The custom style dropdown can be enabled via the `importcss` plugin bundled with admin module. ([Doc](https://www.tiny.cloud/docs/tinymce/6/importcss/)) Use the below code in `app/_config.php`: ```php use SilverStripe\Forms\HTMLEditor\TinyMCEConfig; TinyMCEConfig::get('cms') - ->addButtonsToLine(1, 'styleselect') + ->addButtonsToLine(1, 'styles') ->setOption('importcss_append', true); ``` @@ -44,24 +52,26 @@ Any CSS classes within this file will be automatically added to the `WYSIWYG` ed For instance, to add the color 'red' as an option within the `WYSIWYG` add the following to the `editor.css` - ```css .red { color: red; } ``` -Adding a tag to the selector will automatically wrap with this tag. For example : + +Adding a tag to the selector will automatically wrap with this tag. For example: + ```css h4.red { color: red; } ``` + will add an `h4` tag to the selected block. For further customisation, customize the `style_formats` option. `style_formats` won't be applied if you do not enable `importcss_append`. Here is a working example to get you started.   -See related [tinymce doc](https://www.tinymce.com/docs/configure/content-formatting/#style_formats). +See related [tinymce doc](https://www.tiny.cloud/docs/tinymce/6/user-formatting-options/#style_formats). ```php use SilverStripe\Forms\HTMLEditor\TinyMCEConfig; @@ -101,14 +111,13 @@ $formats = [ ]; TinyMCEConfig::get('cms') - ->addButtonsToLine(1, 'styleselect') + ->addButtonsToLine(1, 'styles') ->setOptions([ 'importcss_append' => true, 'style_formats' => $formats, ]); ``` - ## API Documentation * [HtmlEditorConfig](api:SilverStripe\Forms\HTMLEditor\HtmlEditorConfig) diff --git a/en/04_Changelogs/5.0.0.md b/en/04_Changelogs/5.0.0.md index 60babd731..342617894 100644 --- a/en/04_Changelogs/5.0.0.md +++ b/en/04_Changelogs/5.0.0.md @@ -11,6 +11,8 @@ title: 5.0.0 (unreleased) - [General changes](#api-general) - [ORM](#api-orm) - [Dependency changes](#dependency-changes) + - [General changes](#dep-general) + - [TinyMCE upgraded from 4 to 6](#tinymce6) - [Features and enhancements](#features-and-enhancements) - [Other features](#other-features) - [Bugfixes](#bugfixes) @@ -121,10 +123,32 @@ their aliases (applied by setting a string key for the array) were being ignored ## Dependency changes +### General changes {#dep-general} + - Various Symfony dependencies have been upgraded from 4.x to 6.x. A small number of code changes were made in silverstripe/framework to work with the symfony 6.x dependencies. - silverstripe/graphql v3 is no longer supported. It is recommended that you ensure you are using graphl v4 in your Silverstripe CMS 4 project before upgrading to Silverstripe CMS 5. There is [documentation for the upgrade process here](https://docs.silverstripe.org/en/4/upgrading/upgrading_to_graphql_4/). - PHPUnit 5.7 is no longer supported. It is recommended that you ensure your tests are running with PHPUnit 9 in your Silverstripe CMS 4 project before upgrading to Silverstripe CMS 5. There is [documentation for the upgrade process here](https://docs.silverstripe.org/en/4/upgrading/phpunit9/). +### TinyMCE upgraded from 4 to 6 {#tinymce6} + +TinyMCE has been upgraded up two major versions from 4 to 6. The API for []() and []() haven't changed at all, but there have been some changes to plugins and options which may affect your projects. Here are some notable changes: + +- The `styleselect` option for selecting a css style has changed to `styles` +- The `spellchecker` plugin is now a premium "[Spell Checker Pro](https://www.tiny.cloud/docs/tinymce/6/introduction-to-tiny-spellchecker/)" plugin through TinyMCE cloud (though the `browser_spellcheck` options still works and is enabled by default) +- The "paste from Microsoft Word" functionality is now part of a premium "[PowerPaste](https://www.tiny.cloud/docs/tinymce/6/introduction-to-powerpaste/)" plugin through TinyMCE cloud + - There is an [open call for maintainers](https://github.com/tinymce/tinymce/discussions/7487) for converting the old functionality into a new open source plugin +- The UI API has changed, which will affect any custom plugins you may be using. Notably: + - most `addX()` functions have been moved from `editor` to `editor.ui.registry` - e.g. `editor.addButton()` is now `editor.ui.registry.addButton()` + - `onclick` functions on buttons have been changed to `onAction`. + +There were a lot more changes than just those, so you may want to also check out the following resources: + +- [Docs for upgrading from 4 to 5](https://www.tiny.cloud/docs/migration-from-4x/) +- [Docs for upgrading from 5 to 6](https://www.tiny.cloud/docs/tinymce/6/migration-from-5x/) +- [List of open source plugins for TinyMCE 6](https://www.tiny.cloud/docs/tinymce/6/plugins/#open-source-plugins) +- [List of toolbar buttons available for TinyMCE 6](https://www.tiny.cloud/docs/tinymce/6/available-toolbar-buttons/) +- [Create a plugin](https://www.tiny.cloud/docs/tinymce/6/creating-a-plugin/) + ## Features and enhancements {#features-and-enhancements} ### Extension changes