|
| 1 | +# CKEditor 5 - JavaScript API |
| 2 | + |
| 3 | +WoltLab Suite 6.0 ships with a customized version of CKEditor 5 that is enriched by multiple plugins to integrate into the framework. |
| 4 | +The editor can be accessed through an abstraction layer and event system to interact with basic functionality and to alter its initialization process. |
| 5 | + |
| 6 | +## The `Ckeditor` API |
| 7 | + |
| 8 | +The `WoltLabSuite/Core/Component/Ckeditor` API offers multiple helper methods to interface with CKEditor and to insert and extract content. |
| 9 | +You can get access to the instance using the `getCkeditor()` and `getCkeditorById()` methods once the editor has been initialized. |
| 10 | + |
| 11 | +Please refer to the typings of this component to learn about its API methods. |
| 12 | + |
| 13 | +## The Event System for CKEditor 5 |
| 14 | + |
| 15 | +The event system of CKEditor 5 was designed for actions from within the editor but not to interface with the “outside world”. |
| 16 | +In order to provide a deeper integration there is `WoltLabSuite/Core/Component/Ckeditor/Event` and its exported function `listenToCkeditor()`. |
| 17 | + |
| 18 | +`listenToCkeditor()` expects the source element of the editor which usually is the `<textarea>` for the content. |
| 19 | +There is also `dispatchToCkeditor()` which is considered to be an internal API used from within the editor. |
| 20 | + |
| 21 | +### Lifecycle of CKEditor 5 |
| 22 | + |
| 23 | +The initialization of any CKEditor 5 instance is asynchronous and goes through multiple steps to collect the data needed to initialize the editor. |
| 24 | + |
| 25 | +1. `setupFeatures()` is an override to disable the available features of this instance. The list of features becomes immutable after this event. |
| 26 | +2. `setupConfiguration()` is called at the end of the configuration phase and allows changes to the `EditorConfig` before it is passed to CKEditor. |
| 27 | +3. The `ready()` is fired as soon as the editor has been fully initialized and provides the `Ckeditor` object to access the editor. |
| 28 | +4. `collectMetaData()` is used in inline editors to request the injection of additional payloads that should be included in the server request. |
| 29 | +5. `reset()` notifies that the editor is being fully reset and reliant components should perform a reset themselves. |
| 30 | +6. `destroy()` signals that the editor has been destroyed and is no longer available. |
| 31 | + |
| 32 | +### Custom BBCode Buttons in the Editor Toolbar |
| 33 | + |
| 34 | +Custom buttons in the editor can be injected by pushing them to the toolbar in `setupConfiguration()`. |
| 35 | +This is implicitly takes place for buttons that are registered through the BBCode system and are set to appear in the editor. |
| 36 | + |
| 37 | +```ts |
| 38 | +listenToCkeditor(element).setupConfiguration(({ configuration }) => { |
| 39 | + configuration.woltlabBbcode.push({ |
| 40 | + icon: "fire;false", |
| 41 | + name: "foo", |
| 42 | + label: "Button label for foo", |
| 43 | + }); |
| 44 | +}); |
| 45 | +``` |
| 46 | + |
| 47 | +Clicks on the buttons are forwarded through the `bbcode()` event. |
| 48 | +The only data passed to the callback is the name of the BBCode that was invoked. |
| 49 | + |
| 50 | +The default action of the custom buttons is to insert the BBCode into the editor, including the ability to wrap the selected text in the BBCode tags. |
| 51 | +Every event listener registered to this event MUST return a boolean to indicate if it wants to suppress the insertion of the text BBCode, for example to open a dialog or trigger another action. |
| 52 | + |
| 53 | +```ts |
| 54 | +listenToCkeditor(element).ready(({ ckeditor }) => { |
| 55 | + listenToCkeditor(element).bbcode(({ bbcode }) => { |
| 56 | + if (bbcode !== "foo") { |
| 57 | + return false; |
| 58 | + } |
| 59 | + |
| 60 | + // Do something when the button for `foo` was clicked. |
| 61 | + |
| 62 | + return true; |
| 63 | + }); |
| 64 | +}); |
| 65 | +``` |
| 66 | + |
| 67 | +### Submit the Editor on Enter |
| 68 | + |
| 69 | +The editor supports the special feature flag `submitOnEnter` that can be enabled through `setupFeatures()`. |
| 70 | +Once enabled it changes the behavior of the Enter key to signal that the contents should be submitted to the server. |
| 71 | + |
| 72 | +```ts |
| 73 | +listenToCkeditor(element).setupFeatures(({ features }) => { |
| 74 | + features.submitOnEnter = true; |
| 75 | +}); |
| 76 | +``` |
| 77 | + |
| 78 | +You can subscribe to the `submitOnEnter()` to be notified when the Enter key was pressed and the editor is not empty. |
| 79 | +The contents of the editor is provided through the `html` key. |
| 80 | + |
| 81 | +This mode does not suppress the insertion of hard breaks through Shift + Enter. |
| 82 | + |
| 83 | +```ts |
| 84 | +listenToCkeditor(element).submitOnEnter(({ ckeditor, html }) => { |
| 85 | + // Do something with the resulting `html`. |
| 86 | +}); |
| 87 | +``` |
0 commit comments