From ce65ca855300d4d5819066ed6ee8232d57201f0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotrek=20Koszuli=C5=84ski?= Date: Mon, 1 Mar 2021 15:28:42 +0100 Subject: [PATCH 1/8] Created migration guide for v26.0.0 and updated the error description for missing soft requirement. --- .../migration-from-ckeditor-4.md} | 4 +- .../guides/migration/migration-to-26.0.0.md | 183 ++++++++++++++++++ docs/umberto.json | 11 +- .../ckeditor5-core/src/plugincollection.js | 29 +-- 4 files changed, 212 insertions(+), 15 deletions(-) rename docs/builds/guides/{migrate.md => migration/migration-from-ckeditor-4.md} (99%) create mode 100644 docs/builds/guides/migration/migration-to-26.0.0.md diff --git a/docs/builds/guides/migrate.md b/docs/builds/guides/migration/migration-from-ckeditor-4.md similarity index 99% rename from docs/builds/guides/migrate.md rename to docs/builds/guides/migration/migration-from-ckeditor-4.md index 15255a02b36..fd6e109206a 100644 --- a/docs/builds/guides/migrate.md +++ b/docs/builds/guides/migration/migration-from-ckeditor-4.md @@ -4,8 +4,8 @@ # * Underline that migrating is a complex and important task. # * List and clarify the things that need attention when migrating. -category: builds-guides -order: 260 +category: builds-migration +order: 10 --- # Migration from CKEditor 4 diff --git a/docs/builds/guides/migration/migration-to-26.0.0.md b/docs/builds/guides/migration/migration-to-26.0.0.md new file mode 100644 index 00000000000..4d8394f30ca --- /dev/null +++ b/docs/builds/guides/migration/migration-to-26.0.0.md @@ -0,0 +1,183 @@ +--- +category: builds-migration +order: 20 +--- + +# Migration to 26.0.0 + +For the entire list of changes introduced in version 26.0.0 see the [changelog for CKEditor 5 v26.0.0](https://github.com/ckeditor/ckeditor5/blob/master/CHANGELOG.md#2600-2021-03-01). + +Below, we will go through the most important changes that require your attention when upgrading to 26.0.0. + +## Soft requirements + +While [allowing extending builds](https://github.com/ckeditor/ckeditor5/issues/8395) with additional plugins without rebuilding the bundle (concept also called "DLLs"), we had to decouple certain sets of plugins. This has lead to the introduction of "soft requirements". + +Normally, each plugin had its direct requirements that would be automatically loaded by the editor before that plugin is loaded. Those plugins were specified in `static get() {}` callback of a plugin class in form of plugin constructors (dependencies). + +Starting from 26.0.0 not all plugins can be directly imported by other plugins. However, a plugin can define that it requires another plugin (called for example `'Foo'`) by returning a string from `static get() {}`. This tells the editor that such a plugin must be provided by the integrator (you) either prior to building (via {@link module:core/editor/editor~Editor.builtinPlugins `Editor.builtinPlugins`}) or when creating a new instance of the editor (e.g. via {@link module:core/editor/editorconfig~EditorConfig#plugins `config.plugins`}). + +Therefore, when upgrading to version 26.0.0 you may stumble upon `plugincollection-soft-required` error. This tells you that some dependencies are now missing and you need to provide them. + +### List of known soft requirements + +- Make sure to add {@link module:cloud-services/cloudservices~CloudServices `CloudServices`} to the editor plugins when using the `CloudServicesUploadAdapter` or `EasyImage` features. +- Make sure to add {@link module:image/image~Image `Image`} and {@link module:image/imageupload~ImageUpload `ImageUpload`} to the editor plugins when using the `EasyImage` feature. +- Make sure to add {@link module:adapter-ckfinder/uploadadapter~UploadAdapter `CKFinderUploadAdapter`}, {@link module:image/image~Image `Image`}, and {@link module:link/link~Link `Link`} features to the editor plugins when using the `CKFinder` feature. +- Make sure to add {@link module:paragraph/paragraph~Paragraph `Paragraph`} to the editor plugins when using the `Title` feature. +- Make sure to add {@link module:paragraph/paragraph~Paragraph `Paragraph`} to the editor plugins when using the `List` feature. +- Make sure to add {@link module:image/image~Image `Image`} to the editor plugins when using the `LinkImage` feature. +- Make sure to add {@link module:image/image~Image `Image`} to the editor plugins when using the `LinkImage` feature. +- Make sure to add {@link module:cloud-services/cloudservices~CloudServices `CloudServices`} to the editor plugins when using the `ExportPdf` feature. +- Make sure to add {@link module:cloud-services/cloudservices~CloudServices `CloudServices`} to the editor plugins when using the `ExportWord` feature. + +### Upgrade method + +Let's suppose that you were passing plugins directly to `Editor.create()` via `config.plugins` and this was your setup: + +```js +import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor'; +import EssentialsPlugin from '@ckeditor/ckeditor5-essentials/src/essentials'; +import UploadAdapterPlugin from '@ckeditor/ckeditor5-adapter-ckfinder/src/uploadadapter'; +import AutoformatPlugin from '@ckeditor/ckeditor5-autoformat/src/autoformat'; +import BoldPlugin from '@ckeditor/ckeditor5-basic-styles/src/bold'; +import ItalicPlugin from '@ckeditor/ckeditor5-basic-styles/src/italic'; +import BlockQuotePlugin from '@ckeditor/ckeditor5-block-quote/src/blockquote'; +import EasyImagePlugin from '@ckeditor/ckeditor5-easy-image/src/easyimage'; +import HeadingPlugin from '@ckeditor/ckeditor5-heading/src/heading'; +import ImagePlugin from '@ckeditor/ckeditor5-image/src/image'; +import ImageCaptionPlugin from '@ckeditor/ckeditor5-image/src/imagecaption'; +import ImageStylePlugin from '@ckeditor/ckeditor5-image/src/imagestyle'; +import ImageToolbarPlugin from '@ckeditor/ckeditor5-image/src/imagetoolbar'; +import LinkPlugin from '@ckeditor/ckeditor5-link/src/link'; +import ListPlugin from '@ckeditor/ckeditor5-list/src/list'; +import ParagraphPlugin from '@ckeditor/ckeditor5-paragraph/src/paragraph'; + +ClassicEditor + .create( document.querySelector( '#editor'), { + plugins: [ + EssentialsPlugin, + AutoformatPlugin, + BoldPlugin, + ItalicPlugin, + BlockQuotePlugin, + HeadingPlugin, + ImagePlugin, + ImageCaptionPlugin, + ImageStylePlugin, + ImageToolbarPlugin, + EasyImagePlugin, + ImageUploadPlugin, + LinkPlugin, + ListPlugin, + ParagraphPlugin + ], + toolbar: [ + 'heading', + 'bold', + 'italic', + 'link', + 'bulletedList', + 'numberedList', + 'uploadImage', + 'blockQuote', + 'undo', + 'redo' + ], + image: { + toolbar: [ + 'imageStyle:full', + 'imageStyle:side', + '|', + 'imageTextAlternative' + ] + } + } ) + .then( editor => { + console.log( editor ); + } ) + .catch( error => { + console.error( error ); + } ); +``` + +Based on the list above (or the error being thrown when you upgraded your packages), you can check that you need to add: + +* `ImageUpload` because you use `EasyImage`. +* `CloudServices` because you use `EasyImage`. + +After the upgrade, the setup should look like this: + +```js +import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor'; +import EssentialsPlugin from '@ckeditor/ckeditor5-essentials/src/essentials'; +import UploadAdapterPlugin from '@ckeditor/ckeditor5-adapter-ckfinder/src/uploadadapter'; +import AutoformatPlugin from '@ckeditor/ckeditor5-autoformat/src/autoformat'; +import BoldPlugin from '@ckeditor/ckeditor5-basic-styles/src/bold'; +import ItalicPlugin from '@ckeditor/ckeditor5-basic-styles/src/italic'; +import BlockQuotePlugin from '@ckeditor/ckeditor5-block-quote/src/blockquote'; +import EasyImagePlugin from '@ckeditor/ckeditor5-easy-image/src/easyimage'; +import HeadingPlugin from '@ckeditor/ckeditor5-heading/src/heading'; +import ImagePlugin from '@ckeditor/ckeditor5-image/src/image'; +import ImageCaptionPlugin from '@ckeditor/ckeditor5-image/src/imagecaption'; +import ImageStylePlugin from '@ckeditor/ckeditor5-image/src/imagestyle'; +import ImageToolbarPlugin from '@ckeditor/ckeditor5-image/src/imagetoolbar'; +import LinkPlugin from '@ckeditor/ckeditor5-link/src/link'; +import ListPlugin from '@ckeditor/ckeditor5-list/src/list'; +import ParagraphPlugin from '@ckeditor/ckeditor5-paragraph/src/paragraph'; + +// ADDED +import ImageUploadPlugin from '@ckeditor/ckeditor5-image/src/imageupload'; +import CloudServicesPlugin from '@ckeditor/ckeditor5-cloud-services/src/cloudservices'; + +ClassicEditor + .create( document.querySelector( '#editor'), { + plugins: [ + EssentialsPlugin, + AutoformatPlugin, + BoldPlugin, + ItalicPlugin, + BlockQuotePlugin, + HeadingPlugin, + ImagePlugin, + ImageCaptionPlugin, + ImageStylePlugin, + ImageToolbarPlugin, + EasyImagePlugin, + ImageUploadPlugin, + LinkPlugin, + ListPlugin, + ParagraphPlugin, + + // ADDED + ImageUploadPlugin, + CloudServicesPlugin + ], + toolbar: [ + 'heading', + 'bold', + 'italic', + 'link', + 'bulletedList', + 'numberedList', + 'uploadImage', + 'blockQuote', + 'undo', + 'redo' + ], + image: { + toolbar: [ + 'imageStyle:full', + 'imageStyle:side', + '|', + 'imageTextAlternative' + ] + } + } ) + .then( editor => { + console.log( editor ); + } ) + .catch( error => { + console.error( error ); + } ); +``` diff --git a/docs/umberto.json b/docs/umberto.json index d2fe543a6a4..84c33bed209 100644 --- a/docs/umberto.json +++ b/docs/umberto.json @@ -31,7 +31,8 @@ "features/paste-from-word.html": "features/pasting/paste-from-word.html", "features/mathtype.html": "features/math-equations.html", "features/spell-checker.html": "features/spelling-and-grammar-checking.html", - "features/blocktoolbar.html": "features/toolbar/blocktoolbar.html" + "features/blocktoolbar.html": "features/toolbar/blocktoolbar.html", + "builds/guides/migrate.html": "builds/guides/migrate/migration-from-ckeditor-4.html" }, "scripts": { "snippet-adapter": "../scripts/docs/snippetadapter", @@ -108,11 +109,17 @@ "slug": "development", "order": 200 }, + { + "name": "Migration", + "id": "builds-migration", + "slug": "migration", + "order": 300 + }, { "name": "Support", "id": "builds-support", "slug": "support", - "order": 300 + "order": 400 } ] } diff --git a/packages/ckeditor5-core/src/plugincollection.js b/packages/ckeditor5-core/src/plugincollection.js index 5a5257a5698..b26208c437a 100644 --- a/packages/ckeditor5-core/src/plugincollection.js +++ b/packages/ckeditor5-core/src/plugincollection.js @@ -308,25 +308,32 @@ export default class PluginCollection { if ( parentPluginConstructor ) { /** - * A required "soft" dependency was not found on plugin list. + * A required "soft" dependency was not found on the plugin list. * - * Plugin classes (constructors) need to be provided to the editor before they can be loaded by name. - * This is usually done in CKEditor 5 builds by setting the - * {@link module:core/editor/editor~Editor.builtinPlugins} property. Alternatively they can be provided using - * {@link module:core/editor/editorconfig~EditorConfig#plugins} or - * {@link module:core/editor/editorconfig~EditorConfig#extraPlugins} configuration. + * When configuring the editor, either prior to building (via + * {@link module:core/editor/editor~Editor.builtinPlugins `Editor.builtinPlugins`}) or when + * creating a new instance of the editor (e.g. via + * {@link module:core/editor/editorconfig~EditorConfig#plugins `config.plugins`}), you need to provide + * some of the dependencies of other plugins that you used. * - * **If you see this warning when using one of the {@glink builds/index CKEditor 5 Builds}**, it means - * that you didn't add the required plugin to the plugins list when loading the editor. + * This error is thrown when one of these dependencies was not provided. The name of the missing plugin + * can be found in `missingPlugin` and the plugin that required it in `requiredBy`. + * + * In order to resolve it, you need to import the missing plugin and add it to the + * current list of plugins (`Editor.builtinPlugins` or `config.plugins`/`config.extraPlugins`). + * + * Soft requirements were introduced in version 26.0.0. If you happen to stumble upon this error + * when upgrading to version 26.0.0, read also the + * {@glink builds/guides/migration/migration-to-26.0.0 Migration to 26.0.0} guide. * * @error plugincollection-soft-required - * @param {String} plugin The name of the required plugin. - * @param {String} requiredBy The name of the plugin that was requiring other plugin. + * @param {String} missingPlugin The name of the required plugin. + * @param {String} requiredBy The name of the plugin that requires the other plugin. */ throw new CKEditorError( 'plugincollection-soft-required', context, - { plugin, requiredBy: getPluginName( parentPluginConstructor ) } + { missingPlugin: plugin, requiredBy: getPluginName( parentPluginConstructor ) } ); } From cc192da5379972804223e5de662c68e571eff525 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotrek=20Koszuli=C5=84ski?= Date: Mon, 1 Mar 2021 15:40:18 +0100 Subject: [PATCH 2/8] Fixed the redirect path. --- docs/umberto.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/umberto.json b/docs/umberto.json index 84c33bed209..387180e1463 100644 --- a/docs/umberto.json +++ b/docs/umberto.json @@ -32,7 +32,7 @@ "features/mathtype.html": "features/math-equations.html", "features/spell-checker.html": "features/spelling-and-grammar-checking.html", "features/blocktoolbar.html": "features/toolbar/blocktoolbar.html", - "builds/guides/migrate.html": "builds/guides/migrate/migration-from-ckeditor-4.html" + "builds/guides/migrate.html": "builds/guides/migration/migration-from-ckeditor-4.html" }, "scripts": { "snippet-adapter": "../scripts/docs/snippetadapter", From 333d7cee34ed7123cbbc45bfb21ea93b933b2667 Mon Sep 17 00:00:00 2001 From: godai78 Date: Tue, 2 Mar 2021 08:38:10 +0100 Subject: [PATCH 3/8] Docs: minor fixes. --- .../guides/migration/migration-to-26.0.0.md | 28 +++++++++---------- .../ckeditor5-core/src/plugincollection.js | 2 +- 2 files changed, 14 insertions(+), 16 deletions(-) diff --git a/docs/builds/guides/migration/migration-to-26.0.0.md b/docs/builds/guides/migration/migration-to-26.0.0.md index 4d8394f30ca..8e245f4e3b6 100644 --- a/docs/builds/guides/migration/migration-to-26.0.0.md +++ b/docs/builds/guides/migration/migration-to-26.0.0.md @@ -7,13 +7,13 @@ order: 20 For the entire list of changes introduced in version 26.0.0 see the [changelog for CKEditor 5 v26.0.0](https://github.com/ckeditor/ckeditor5/blob/master/CHANGELOG.md#2600-2021-03-01). -Below, we will go through the most important changes that require your attention when upgrading to 26.0.0. +Listed below are the most important changes that require your attention when upgrading to 26.0.0. ## Soft requirements -While [allowing extending builds](https://github.com/ckeditor/ckeditor5/issues/8395) with additional plugins without rebuilding the bundle (concept also called "DLLs"), we had to decouple certain sets of plugins. This has lead to the introduction of "soft requirements". +While [allowing to extend builds](https://github.com/ckeditor/ckeditor5/issues/8395) with additional plugins without rebuilding the bundle (concept also called "DLLs"), certain sets of plugins had to be decoupled. This has lead to the introduction of the "soft requirements". -Normally, each plugin had its direct requirements that would be automatically loaded by the editor before that plugin is loaded. Those plugins were specified in `static get() {}` callback of a plugin class in form of plugin constructors (dependencies). +Normally, each plugin had its direct requirements that would be automatically loaded by the editor before that plugin is loaded. Those plugins were specified in `static get() {}` callback of a plugin class in the form of plugin constructors (dependencies). Starting from 26.0.0 not all plugins can be directly imported by other plugins. However, a plugin can define that it requires another plugin (called for example `'Foo'`) by returning a string from `static get() {}`. This tells the editor that such a plugin must be provided by the integrator (you) either prior to building (via {@link module:core/editor/editor~Editor.builtinPlugins `Editor.builtinPlugins`}) or when creating a new instance of the editor (e.g. via {@link module:core/editor/editorconfig~EditorConfig#plugins `config.plugins`}). @@ -21,19 +21,17 @@ Therefore, when upgrading to version 26.0.0 you may stumble upon `plugincollecti ### List of known soft requirements -- Make sure to add {@link module:cloud-services/cloudservices~CloudServices `CloudServices`} to the editor plugins when using the `CloudServicesUploadAdapter` or `EasyImage` features. -- Make sure to add {@link module:image/image~Image `Image`} and {@link module:image/imageupload~ImageUpload `ImageUpload`} to the editor plugins when using the `EasyImage` feature. -- Make sure to add {@link module:adapter-ckfinder/uploadadapter~UploadAdapter `CKFinderUploadAdapter`}, {@link module:image/image~Image `Image`}, and {@link module:link/link~Link `Link`} features to the editor plugins when using the `CKFinder` feature. -- Make sure to add {@link module:paragraph/paragraph~Paragraph `Paragraph`} to the editor plugins when using the `Title` feature. -- Make sure to add {@link module:paragraph/paragraph~Paragraph `Paragraph`} to the editor plugins when using the `List` feature. -- Make sure to add {@link module:image/image~Image `Image`} to the editor plugins when using the `LinkImage` feature. -- Make sure to add {@link module:image/image~Image `Image`} to the editor plugins when using the `LinkImage` feature. -- Make sure to add {@link module:cloud-services/cloudservices~CloudServices `CloudServices`} to the editor plugins when using the `ExportPdf` feature. -- Make sure to add {@link module:cloud-services/cloudservices~CloudServices `CloudServices`} to the editor plugins when using the `ExportWord` feature. +* Make sure to add {@link module:cloud-services/cloudservices~CloudServices `CloudServices`} to the editor plugins when using the `CloudServicesUploadAdapter` or `EasyImage` features. +* Make sure to add {@link module:image/image~Image `Image`} and {@link module:image/imageupload~ImageUpload `ImageUpload`} to the editor plugins when using the `EasyImage` feature. +* Make sure to add {@link module:adapter-ckfinder/uploadadapter~UploadAdapter `CKFinderUploadAdapter`}, {@link module:image/image~Image `Image`}, and {@link module:link/link~Link `Link`} features to the editor plugins when using the `CKFinder` feature. +* Make sure to add {@link module:paragraph/paragraph~Paragraph `Paragraph`} to the editor plugins when using the `Title` feature. +* Make sure to add {@link module:paragraph/paragraph~Paragraph `Paragraph`} to the editor plugins when using the `List` feature. +* Make sure to add {@link module:image/image~Image `Image`} to the editor plugins when using the `LinkImage` feature. +* Make sure to add {@link module:cloud-services/cloudservices~CloudServices `CloudServices`} to the editor plugins when using the `ExportPdf` or `ExportWord` features. ### Upgrade method -Let's suppose that you were passing plugins directly to `Editor.create()` via `config.plugins` and this was your setup: +Before, when you were passing plugins directly to `Editor.create()` via `config.plugins`, this would be your setup: ```js import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor'; @@ -103,10 +101,10 @@ ClassicEditor Based on the list above (or the error being thrown when you upgraded your packages), you can check that you need to add: -* `ImageUpload` because you use `EasyImage`. +* `ImageUpload` because you use `EasyImage`, * `CloudServices` because you use `EasyImage`. -After the upgrade, the setup should look like this: +After the upgrade, the setup should therefore look like this: ```js import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor'; diff --git a/packages/ckeditor5-core/src/plugincollection.js b/packages/ckeditor5-core/src/plugincollection.js index b26208c437a..b79ee8e8cda 100644 --- a/packages/ckeditor5-core/src/plugincollection.js +++ b/packages/ckeditor5-core/src/plugincollection.js @@ -314,7 +314,7 @@ export default class PluginCollection { * {@link module:core/editor/editor~Editor.builtinPlugins `Editor.builtinPlugins`}) or when * creating a new instance of the editor (e.g. via * {@link module:core/editor/editorconfig~EditorConfig#plugins `config.plugins`}), you need to provide - * some of the dependencies of other plugins that you used. + * some of the dependencies for other plugins that you used. * * This error is thrown when one of these dependencies was not provided. The name of the missing plugin * can be found in `missingPlugin` and the plugin that required it in `requiredBy`. From 4e58797bf0505fd779efa103831c948f484cbbc1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Piotrek=20Koszuli=C5=84ski?= Date: Tue, 2 Mar 2021 09:03:18 +0100 Subject: [PATCH 4/8] Updated the test. --- packages/ckeditor5-core/tests/plugincollection.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/ckeditor5-core/tests/plugincollection.js b/packages/ckeditor5-core/tests/plugincollection.js index 22585396f98..595e65f25f3 100644 --- a/packages/ckeditor5-core/tests/plugincollection.js +++ b/packages/ckeditor5-core/tests/plugincollection.js @@ -503,7 +503,7 @@ describe( 'PluginCollection', () => { throw new Error( 'Test error: this promise should not be resolved successfully' ); } ); } catch ( err ) { - assertCKEditorError( err, /^plugincollection-soft-required/, editor, { plugin: 'Baz', requiredBy: 'Foo' } ); + assertCKEditorError( err, /^plugincollection-soft-required/, editor, { missingPlugin: 'Baz', requiredBy: 'Foo' } ); } } ); From 2e84737a948b89818cc97f4f93eac9f83ac01e8f Mon Sep 17 00:00:00 2001 From: Kuba Niegowski Date: Tue, 2 Mar 2021 11:26:58 +0100 Subject: [PATCH 5/8] Added information about changes in keystroke handling on macOS. --- docs/builds/guides/migration/migration-to-26.0.0.md | 5 +++++ packages/ckeditor5-utils/src/keyboard.js | 4 ++++ 2 files changed, 9 insertions(+) diff --git a/docs/builds/guides/migration/migration-to-26.0.0.md b/docs/builds/guides/migration/migration-to-26.0.0.md index 8e245f4e3b6..749b6f972a4 100644 --- a/docs/builds/guides/migration/migration-to-26.0.0.md +++ b/docs/builds/guides/migration/migration-to-26.0.0.md @@ -179,3 +179,8 @@ ClassicEditor console.error( error ); } ); ``` + +## Keystrokes + +Starting from 26.0.0 the {@link module:utils/keystrokehandler~KeystrokeHandler `KeystrokeHandler`} is not automatically binding to both Ctrl and Cmd keys on macOS as before, it's translating Ctrl key to Cmd key and handling only that keystroke. So if there was a registered keystroke `Ctrl+A` it is translated to `Cmd+A` on macOS. To be able to disable translation of some keystroke the forced modifier should be used: `Ctrl!+A` (note the exclamation mark). + diff --git a/packages/ckeditor5-utils/src/keyboard.js b/packages/ckeditor5-utils/src/keyboard.js index fdd2d41febd..22078f72384 100644 --- a/packages/ckeditor5-utils/src/keyboard.js +++ b/packages/ckeditor5-utils/src/keyboard.js @@ -93,6 +93,10 @@ export function getCode( key ) { * * Note: Only keystrokes with a single non-modifier key are supported (e.g. `ctrl+A` is OK, but `ctrl+A+B` is not). * + * Note: On macOS keystrokes handling is translating `Ctrl` key to `Cmd` key and handling only that keystroke. + * So if there was a registered keystroke `Ctrl+A` it is translated to `Cmd+A` on macOS. To be able to disable + * translation of some keystroke the forced modifier should be used: `Ctrl!+A` (note the exclamation mark). + * * @param {String|Array.} keystroke Keystroke definition. * @returns {Number} Keystroke code. */ From 78c5bf8212e8bedf5b33cfc762a551e11e1aa3ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Smyrek?= Date: Tue, 2 Mar 2021 12:02:12 +0100 Subject: [PATCH 6/8] Added information about unified naming convention for buttons and commands --- .../guides/migration/migration-to-26.0.0.md | 34 ++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/docs/builds/guides/migration/migration-to-26.0.0.md b/docs/builds/guides/migration/migration-to-26.0.0.md index 749b6f972a4..a1987eabc36 100644 --- a/docs/builds/guides/migration/migration-to-26.0.0.md +++ b/docs/builds/guides/migration/migration-to-26.0.0.md @@ -182,5 +182,37 @@ ClassicEditor ## Keystrokes -Starting from 26.0.0 the {@link module:utils/keystrokehandler~KeystrokeHandler `KeystrokeHandler`} is not automatically binding to both Ctrl and Cmd keys on macOS as before, it's translating Ctrl key to Cmd key and handling only that keystroke. So if there was a registered keystroke `Ctrl+A` it is translated to `Cmd+A` on macOS. To be able to disable translation of some keystroke the forced modifier should be used: `Ctrl!+A` (note the exclamation mark). +Starting from 26.0.0 the {@link module:utils/keystrokehandler~KeystrokeHandler `KeystrokeHandler`} is not automatically binding to both Ctrl and Cmd keys on macOS as before, it's translating Ctrl key to Cmd key and handling only that keystroke. So if there was a registered keystroke `Ctrl+A` it is translated to `Cmd+A` on macOS. To be able to disable translation of some keystroke the forced modifier should be used: `Ctrl!+A` (note the exclamation mark). +## Unified button and command naming convention + +The naming conventions for buttons and commands have been reviewed and unified to maintain maximum consistency and provide sane rules that match real-life cases. + +All buttons follow the **verb + noun** (i.e. `insertTable`, `selectAll`) or the **noun** (i.e. `bold`, `mediaEmbed`) convention. + +As for commands it was trickier, because there are many more possible combinations of their names than there are for buttons. For commands, in most cases, the proper name should start with the **action** followed by the **feature** name (i.e. `checkTodoList`, `insertTable`). + +Changes in toolbar buttons (before → after): + +* `imageUpload` → `uploadImage` +* `imageResize` → `resizeImage` +* `imageInsert` → `insertImage` +* `imageResize:*` → `resizeImage:*` + +Changes in command names (before → after): + +* `imageInsert` → `insertImage` +* `imageUpload` → `uploadImage` +* `imageResize` → `resizeImage` +* `forwardDelete` → `deleteForward` +* `todoListCheck` → `checkTodoList` + +The `TodoListCheckCommand` module has been moved to {@link module:list/checktodolistcommand~CheckTodoListCommand `CheckTodoListCommand`}. + +The `ImageInsertCommand` module has been moved to {@link module:image/image/insertimagecommand~InsertImageCommand `InsertImageCommand`}. + +The `ImageResizeCommand` module has been moved to {@link module:image/imageresize/resizeimagecommand~ResizeImageCommand `ResizeImageCommand`}. + +The `ImageUploadCommand` module has been moved to {@link module:image/imageupload/uploadimagecommand~UploadImageCommand `UploadImageCommand`}. + +Old names are still available as aliases. From df769d72892076c120e7076c3f701a10e8d5f2c6 Mon Sep 17 00:00:00 2001 From: godai78 Date: Tue, 2 Mar 2021 12:15:01 +0100 Subject: [PATCH 7/8] Docs: review. --- docs/builds/guides/migration/migration-to-26.0.0.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/builds/guides/migration/migration-to-26.0.0.md b/docs/builds/guides/migration/migration-to-26.0.0.md index a1987eabc36..fde6b2ce207 100644 --- a/docs/builds/guides/migration/migration-to-26.0.0.md +++ b/docs/builds/guides/migration/migration-to-26.0.0.md @@ -182,24 +182,24 @@ ClassicEditor ## Keystrokes -Starting from 26.0.0 the {@link module:utils/keystrokehandler~KeystrokeHandler `KeystrokeHandler`} is not automatically binding to both Ctrl and Cmd keys on macOS as before, it's translating Ctrl key to Cmd key and handling only that keystroke. So if there was a registered keystroke `Ctrl+A` it is translated to `Cmd+A` on macOS. To be able to disable translation of some keystroke the forced modifier should be used: `Ctrl!+A` (note the exclamation mark). +Starting from 26.0.0 the {@link module:utils/keystrokehandler~KeystrokeHandler `KeystrokeHandler`} is not automatically binding to both Ctrl and Cmd keys on macOS as before. Instead, it is translating Ctrl key to Cmd key and handling this keystroke only. So if there was a registered keystroke `Ctrl+A` it is translated to `Cmd+A` on macOS. To be able to disable translation of some keystroke you should use the forced modifier: `Ctrl!+A` (note the exclamation mark). ## Unified button and command naming convention -The naming conventions for buttons and commands have been reviewed and unified to maintain maximum consistency and provide sane rules that match real-life cases. +The naming conventions for both buttons and commands have been reviewed and unified to maintain maximum consistency and provide sane rules that match real-life cases. All buttons follow the **verb + noun** (i.e. `insertTable`, `selectAll`) or the **noun** (i.e. `bold`, `mediaEmbed`) convention. -As for commands it was trickier, because there are many more possible combinations of their names than there are for buttons. For commands, in most cases, the proper name should start with the **action** followed by the **feature** name (i.e. `checkTodoList`, `insertTable`). +It was trickier for commands, because there are more possible name combinations than there are for buttons. For commands, the proper name should start with the **action** followed by the **feature** name (i.e. `checkTodoList`, `insertTable`), in most cases. -Changes in toolbar buttons (before → after): +Toolbar buttons name changes (before → after): * `imageUpload` → `uploadImage` * `imageResize` → `resizeImage` * `imageInsert` → `insertImage` * `imageResize:*` → `resizeImage:*` -Changes in command names (before → after): +Command name changes (before → after): * `imageInsert` → `insertImage` * `imageUpload` → `uploadImage` From e2adb7d1c45cb03db7a9e44ff8284e27565562f5 Mon Sep 17 00:00:00 2001 From: Anna Tomanek Date: Tue, 2 Mar 2021 14:08:58 +0100 Subject: [PATCH 8/8] Docs review. --- .../guides/migration/migration-to-26.0.0.md | 32 +++++++++-------- packages/ckeditor5-utils/src/keyboard.js | 36 +++++++++---------- 2 files changed, 35 insertions(+), 33 deletions(-) diff --git a/docs/builds/guides/migration/migration-to-26.0.0.md b/docs/builds/guides/migration/migration-to-26.0.0.md index fde6b2ce207..3fcc123d3dd 100644 --- a/docs/builds/guides/migration/migration-to-26.0.0.md +++ b/docs/builds/guides/migration/migration-to-26.0.0.md @@ -5,19 +5,19 @@ order: 20 # Migration to 26.0.0 -For the entire list of changes introduced in version 26.0.0 see the [changelog for CKEditor 5 v26.0.0](https://github.com/ckeditor/ckeditor5/blob/master/CHANGELOG.md#2600-2021-03-01). +For the entire list of changes introduced in version 26.0.0, see the [changelog for CKEditor 5 v26.0.0](https://github.com/ckeditor/ckeditor5/blob/master/CHANGELOG.md#2600-2021-03-01). -Listed below are the most important changes that require your attention when upgrading to 26.0.0. +Listed below are the most important changes that require your attention when upgrading to CKEditor 5 v26.0.0. ## Soft requirements -While [allowing to extend builds](https://github.com/ckeditor/ckeditor5/issues/8395) with additional plugins without rebuilding the bundle (concept also called "DLLs"), certain sets of plugins had to be decoupled. This has lead to the introduction of the "soft requirements". +While [allowing to extend builds](https://github.com/ckeditor/ckeditor5/issues/8395) with additional plugins without rebuilding the bundle (a concept also called "DLLs"), certain sets of plugins had to be decoupled. This has lead to the introduction of the "soft requirements". -Normally, each plugin had its direct requirements that would be automatically loaded by the editor before that plugin is loaded. Those plugins were specified in `static get() {}` callback of a plugin class in the form of plugin constructors (dependencies). +Before, each plugin had its direct requirements that would be automatically loaded by the editor before the plugin is loaded. These plugins were specified in the `static get() {}` callback of a plugin class in the form of plugin constructors (dependencies). -Starting from 26.0.0 not all plugins can be directly imported by other plugins. However, a plugin can define that it requires another plugin (called for example `'Foo'`) by returning a string from `static get() {}`. This tells the editor that such a plugin must be provided by the integrator (you) either prior to building (via {@link module:core/editor/editor~Editor.builtinPlugins `Editor.builtinPlugins`}) or when creating a new instance of the editor (e.g. via {@link module:core/editor/editorconfig~EditorConfig#plugins `config.plugins`}). +Starting from v26.0.0 not all plugins can be directly imported by other plugins. However, a plugin can define that it requires another plugin (called for example `'Foo'`) by returning a string from `static get() {}`. This tells the editor that such a plugin must be provided by the integrator (you) either prior to building (via {@link module:core/editor/editor~Editor.builtinPlugins `Editor.builtinPlugins`}) or when creating a new instance of the editor (e.g. via {@link module:core/editor/editorconfig~EditorConfig#plugins `config.plugins`}). -Therefore, when upgrading to version 26.0.0 you may stumble upon `plugincollection-soft-required` error. This tells you that some dependencies are now missing and you need to provide them. +Therefore, when upgrading to version 26.0.0, you may stumble upon the {@link framework/guides/support/error-codes#error-plugincollection-soft-required `plugincollection-soft-required`} error. This tells you that some dependencies are now missing and you need to provide them. ### List of known soft requirements @@ -180,9 +180,11 @@ ClassicEditor } ); ``` -## Keystrokes +## Keystrokes for macOS -Starting from 26.0.0 the {@link module:utils/keystrokehandler~KeystrokeHandler `KeystrokeHandler`} is not automatically binding to both Ctrl and Cmd keys on macOS as before. Instead, it is translating Ctrl key to Cmd key and handling this keystroke only. So if there was a registered keystroke `Ctrl+A` it is translated to `Cmd+A` on macOS. To be able to disable translation of some keystroke you should use the forced modifier: `Ctrl!+A` (note the exclamation mark). +Starting from v26.0.0, the {@link module:utils/keystrokehandler~KeystrokeHandler `KeystrokeHandler`} is not automatically binding to both Ctrl and Cmd keys on macOS as before. Instead, it is translating the Ctrl key to the Cmd key and handling this keystroke only. + +For example, a registered keystroke `Ctrl+A` will now be translated to `Cmd+A` on macOS. To disable the translation of some keystroke, use the forced modifier: `Ctrl!+A` (note the exclamation mark). ## Unified button and command naming convention @@ -190,9 +192,9 @@ The naming conventions for both buttons and commands have been reviewed and unif All buttons follow the **verb + noun** (i.e. `insertTable`, `selectAll`) or the **noun** (i.e. `bold`, `mediaEmbed`) convention. -It was trickier for commands, because there are more possible name combinations than there are for buttons. For commands, the proper name should start with the **action** followed by the **feature** name (i.e. `checkTodoList`, `insertTable`), in most cases. +It was trickier for commands, because there are more possible name combinations than there are for buttons. For commands, the proper name should in most cases start with the **action** followed by the **feature** name (i.e. `checkTodoList`, `insertTable`). -Toolbar buttons name changes (before → after): +Toolbar button name changes (before → after): * `imageUpload` → `uploadImage` * `imageResize` → `resizeImage` @@ -207,12 +209,12 @@ Command name changes (before → after): * `forwardDelete` → `deleteForward` * `todoListCheck` → `checkTodoList` -The `TodoListCheckCommand` module has been moved to {@link module:list/checktodolistcommand~CheckTodoListCommand `CheckTodoListCommand`}. +The `TodoListCheckCommand` module was moved to {@link module:list/checktodolistcommand~CheckTodoListCommand `CheckTodoListCommand`}. -The `ImageInsertCommand` module has been moved to {@link module:image/image/insertimagecommand~InsertImageCommand `InsertImageCommand`}. +The `ImageInsertCommand` module was moved to {@link module:image/image/insertimagecommand~InsertImageCommand `InsertImageCommand`}. -The `ImageResizeCommand` module has been moved to {@link module:image/imageresize/resizeimagecommand~ResizeImageCommand `ResizeImageCommand`}. +The `ImageResizeCommand` module was moved to {@link module:image/imageresize/resizeimagecommand~ResizeImageCommand `ResizeImageCommand`}. -The `ImageUploadCommand` module has been moved to {@link module:image/imageupload/uploadimagecommand~UploadImageCommand `UploadImageCommand`}. +The `ImageUploadCommand` module was moved to {@link module:image/imageupload/uploadimagecommand~UploadImageCommand `UploadImageCommand`}. -Old names are still available as aliases. +The old names are still available as aliases. diff --git a/packages/ckeditor5-utils/src/keyboard.js b/packages/ckeditor5-utils/src/keyboard.js index 22078f72384..5cda3c70f8b 100644 --- a/packages/ckeditor5-utils/src/keyboard.js +++ b/packages/ckeditor5-utils/src/keyboard.js @@ -4,7 +4,7 @@ */ /** - * Set of utils related to keyboard support. + * A set of utilities related to keyboard support. * * @module utils/keyboard */ @@ -26,7 +26,7 @@ const modifiersToGlyphsNonMac = { }; /** - * Object with `keyName => keyCode` pairs for a set of known keys. + * An object with `keyName => keyCode` pairs for a set of known keys. * * Contains: * @@ -44,11 +44,11 @@ const keyCodeNames = Object.fromEntries( ); /** - * Converts a key name or a {@link module:utils/keyboard~KeystrokeInfo keystroke info} into a key code. + * Converts a key name or {@link module:utils/keyboard~KeystrokeInfo keystroke info} into a key code. * * Note: Key names are matched with {@link module:utils/keyboard~keyCodes} in a case-insensitive way. * - * @param {String|module:utils/keyboard~KeystrokeInfo} Key name (see {@link module:utils/keyboard~keyCodes}) + * @param {String|module:utils/keyboard~KeystrokeInfo} A key name (see {@link module:utils/keyboard~keyCodes}) * or a keystroke data object. * @returns {Number} Key or keystroke code. */ @@ -60,7 +60,7 @@ export function getCode( key ) { if ( !keyCode ) { /** - * Unknown key name. Only key names contained by the {@link module:utils/keyboard~keyCodes} can be used. + * Unknown key name. Only key names included in the {@link module:utils/keyboard~keyCodes} can be used. * * @error keyboard-unknown-key * @param {String} key @@ -79,8 +79,8 @@ export function getCode( key ) { } /** - * Parses keystroke and returns a keystroke code that will match the code returned by - * link {@link module:utils/keyboard~getCode} for a corresponding {@link module:utils/keyboard~KeystrokeInfo keystroke info}. + * Parses the keystroke and returns a keystroke code that will match the code returned by + * {@link module:utils/keyboard~getCode} for the corresponding {@link module:utils/keyboard~KeystrokeInfo keystroke info}. * * The keystroke can be passed in two formats: * @@ -93,11 +93,11 @@ export function getCode( key ) { * * Note: Only keystrokes with a single non-modifier key are supported (e.g. `ctrl+A` is OK, but `ctrl+A+B` is not). * - * Note: On macOS keystrokes handling is translating `Ctrl` key to `Cmd` key and handling only that keystroke. - * So if there was a registered keystroke `Ctrl+A` it is translated to `Cmd+A` on macOS. To be able to disable - * translation of some keystroke the forced modifier should be used: `Ctrl!+A` (note the exclamation mark). + * Note: On macOS, keystroke handling is translating the `Ctrl` key to the `Cmd` key and handling only that keystroke. + * For example, a registered keystroke `Ctrl+A` will be translated to `Cmd+A` on macOS. To disable the translation of some keystroke, + * use the forced modifier: `Ctrl!+A` (note the exclamation mark). * - * @param {String|Array.} keystroke Keystroke definition. + * @param {String|Array.} keystroke The keystroke definition. * @returns {Number} Keystroke code. */ export function parseKeystroke( keystroke ) { @@ -111,11 +111,11 @@ export function parseKeystroke( keystroke ) { } /** - * It translates any keystroke string text like `"CTRL+A"` to an - * environment–specific keystroke, i.e. `"⌘A"` on Mac OSX. + * Translates any keystroke string text like `"Ctrl+A"` to an + * environment–specific keystroke, i.e. `"⌘A"` on macOS. * - * @param {String} keystroke Keystroke text. - * @returns {String} Keystroke text specific for the environment. + * @param {String} keystroke The keystroke text. + * @returns {String} The keystroke text specific for the environment. */ export function getEnvKeystrokeText( keystroke ) { let keystrokeCode = parseKeystroke( keystroke ); @@ -150,9 +150,9 @@ export function isArrowKeyCode( keyCode ) { /** * Returns the direction in which the {@link module:engine/model/documentselection~DocumentSelection selection} - * will move when a provided arrow key code is pressed considering the language direction of the editor content. + * will move when the provided arrow key code is pressed considering the language direction of the editor content. * - * For instance, in right–to–left (RTL) content languages, pressing the left arrow means moving selection right (forward) + * For instance, in right–to–left (RTL) content languages, pressing the left arrow means moving the selection right (forward) * in the model structure. Similarly, pressing the right arrow moves the selection left (backward). * * @param {Number} keyCode A key code as in {@link module:utils/keyboard~KeystrokeInfo#keyCode}. @@ -259,7 +259,7 @@ function splitKeystrokeText( keystroke ) { } /** - * Information about a keystroke. + * Information about the keystroke. * * @interface module:utils/keyboard~KeystrokeInfo */