This article describes how to customize CKEditor for Magnolia DXP. The Magnolia documentation covers most of the essentials, but it can be a bit overwhelming at times. This guide aims to streamline the procedure. I’m assuming you already have the essential development tools like Node.js and NPM installed.

Prerequisites

Before you dive into customization, you should familiarize yourself with the CKEditor documentation. Some plugins are included in the default setup, while others must be manually installed.

Step-by-Step Guide

1. Clone the repository

The source code for CKEditor plugins can be found here:

GitLab Repository for ckeditor5-plugins

git clone https://gitlab.com/magnolia-ce/ckeditor5-plugins.git
cd ckeditor5-plugins

2. Build the package

Check to see if the package builds correctly without any changes.

npm install
# Optional but recommended
npx update-browserslist-db@latest
npm run build

Check your environment setup and resolve any issues before proceeding if the build fails.

3. Install or locate the plugin

If necessary, you can install a plugin using the following command:

npm i <name-of-the-plugin>

To access the default plugins, navigate to:

/ckeditor5-plugins/node_modules/@ckeditor

The ckeditor5-word-count plugin, for example, can be found under the above directory.

For details about the plugin, check the ckeditor5-metadata.json file:

{
  "plugins": [
    {
      "name": "Word count",
      "className": "WordCount",
      "description": "Provides the possibility to track the number of words and characters written in the rich-text editor.",
      "docs": "features/word-count.html",
      "path": "src/wordcount.js"
    }
  ]
}

4. Modify the settings

Open the configuration file:

packages/ckeditor5-build/src/ckeditor5.ts

Add the plugin to the import section:

import { WordCount } from '@ckeditor/ckeditor5-word-count';

Then, include it in the BUILTIN_PLUGINS constant:

const BUILTIN_PLUGINS = [
  Essentials,
  WordCount,
  Heading,
  // Other plugins...
];

5. Configure the toolbar and the plugin

Add it to the toolbar if the plugin requires a visual representation. Several plugins don’t require display. Modify the configuration of the plugins in the DEFAULT_CONFIG constant.

const DEFAULT_CONFIG: CustomEditorConfig = {
  toolbar: [
    'sourceEditing',
    '|',
    'bold',
    'italic',
    'strikethrough',
    'specialCharacters',
    '|',
    'numberedList',
    'bulletedList',
    '|',
    'link',
    'mgnlAssetsLink',
    'mgnlPagesLink',
    '|',
    'undo',
    'redo'
  ],
  wordCount: {
    onUpdate: stats => {
      let wordCountContainer = document.querySelector('#word-count-container') as HTMLElement;
      if (!wordCountContainer) {
        wordCountContainer = document.createElement('div');
        wordCountContainer.id = 'word-count-container';

        wordCountContainer.style.padding = '5px';
        wordCountContainer.style.fontSize = '14px';
        wordCountContainer.style.background = '#f5f5f5';
        wordCountContainer.style.borderTop = '1px solid #ddd';
        wordCountContainer.style.textAlign = 'right';

        const editorContainer = document.querySelector('.ck-editor') as HTMLElement;
        editorContainer?.appendChild(wordCountContainer);
      }
      wordCountContainer.innerText = `Words: ${stats.words}, Characters: ${stats.characters}`;
    },
    displayWords: true,
    displayCharacters: true
  },
  fontFamily: {
    // Additional configurations...
  }
};

The configuration above for the WordCount plugin activates the status bar with the counters displayed.聽

6. Build the package

Run the build command:

npm run build

Make sure the build is successful. If you encounter syntax errors, you should use tools like ChatGPT or an IDE to debug and fix them.

7. Integrate a customized CKEditor into Magnolia DXP

Copy the file that was created:

packages/ckeditor5-build/build/ckeditor5.js

to your Magnolia DXP light module:

{magnolia-dxp-light-module-path}/webresources/ckeditor5.js

8. Build and execute your Magnolia DXP project

Build and run your Magnolia DXP project to put the changes into effect.

Resources

Customized CKEditor 5

This guide should help you customize CKEditor 5 for Magnolia DXP. Happy coding! 馃槉