category | meta-title | menu-title | order |
---|---|---|---|
update-guides |
Update to version 26.x | CKEditor 5 Documentation |
Update to v26.x |
98 |
For custom builds, you may try removing the `package-lock.json` or `yarn.lock` files (if applicable) and reinstalling all packages before rebuilding the editor. For best results, make sure you use the most recent package versions.
Released on March 3, 2021.
For the entire list of changes introduced in version 26.0.0, see the release notes for CKEditor 5 v26.0.0.
Listed below are the most important changes that require your attention when upgrading to CKEditor 5 v26.0.0.
While allowing to extend builds with extra plugins without rebuilding the bundle (a concept also called {@link installation/advanced/dll-builds "DLLs"}), we had to decouple certain sets of plugins. This has led to the introduction of the "soft requirements."
Before, each plugin had its direct requirements that would be automatically loaded by the editor before the plugin was loaded. These plugins were specified in the static get() {}
callback of a plugin class in the form of plugin constructors (dependencies).
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 you must provide such a plugin either before building (via {@link module:core/editor/editorEditor.builtinPlugins EditorConfig#plugins Editor.builtinPlugins
}) or when creating a new instance of the editor (for example, via {@link module:core/editor/editorconfigconfig.plugins
}).
Therefore, when upgrading to version 26.0.0, you may stumble upon the {@link 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.
- Add {@link module:cloud-services/cloudservices~CloudServices
CloudServices
} to the editor plugins when using theCloudServicesUploadAdapter
orEasyImage
features. - Add {@link module:image/image
ImageImageUploadImage
} and {@link module:image/imageuploadImageUpload
} to the editor plugins when using theEasyImage
feature. - Add {@link module:adapter-ckfinder/uploadadapter
CKFinderUploadAdapterImageCKFinderUploadAdapter
}, {@link module:image/imageImage
}, and {@link module:link/link~LinkLink
} features to the editor plugins when using theCKFinder
feature. - Add {@link module:paragraph/paragraph~Paragraph
Paragraph
} to the editor plugins when using theTitle
feature. - Add {@link module:paragraph/paragraph~Paragraph
Paragraph
} to the editor plugins when using theList
feature. - Add {@link module:image/image~Image
Image
} to the editor plugins when using theLinkImage
feature. - Add {@link module:cloud-services/cloudservices~CloudServices
CloudServices
} to the editor plugins when using theExportPdf
orExportWord
features.
Before, when you were passing plugins directly to Editor.create()
via config.plugins
, this would be your setup:
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 thrown when you upgraded your packages), you can check that you need to add:
ImageUpload
because you useEasyImage
,CloudServices
because you useEasyImage
.
After the upgrade, the setup should look like this:
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 );
} );
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 just this keystroke.
For example, a registered keystroke Ctrl+A
will now be translated to Cmd+A
on macOS. To block the translation of a keystroke, use the forced modifier: Ctrl!+A
(note the exclamation mark).
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 (for example, insertTable
, selectAll
) or the noun (for example, bold
, mediaEmbed
) convention.
It was trickier for commands because there are more name combinations possible than there are for buttons. For commands, the proper name should usually start with the action followed by the feature name (like checkTodoList
, insertTable
).
Toolbar button name changes (before → after):
imageUpload
→uploadImage
imageResize
→resizeImage
imageInsert
→insertImage
imageResize:*
→resizeImage:*
Command name changes (before → after):
imageInsert
→insertImage
imageUpload
→uploadImage
imageResize
→resizeImage
forwardDelete
→deleteForward
todoListCheck
→checkTodoList
The TodoListCheckCommand
module was moved to {@link module:list/todolist/checktodolistcommand~CheckTodoListCommand CheckTodoListCommand
}.
The ImageInsertCommand
module was moved to {@link module:image/image/insertimagecommand~InsertImageCommand InsertImageCommand
}.
The ImageResizeCommand
module was moved to {@link module:image/imageresize/resizeimagecommand~ResizeImageCommand ResizeImageCommand
}.
The ImageUploadCommand
module was moved to {@link module:image/imageupload/uploadimagecommand~UploadImageCommand UploadImageCommand
}.
The old names are still available as aliases.