Custom Ckeditor Plugin

[Fleur Francour]

Thisguide will show you how to create a simple, basic plugin that will let the users insert timestamps into their content. This is a beginner friendly tutorial, perfect for your first interaction with the CKEditor 5 framework.

We will create a toolbar button that will insert the current date and time at the caret position into the document. If you want to see the final product of this tutorial before you plunge in, check out the live demo below.

The easiest way to set up your project is to grab the starter files from our Github repository for this tutorial. We gathered all the necessary dependencies there, including some CKEditor 5 packages and other files needed to build the editor. If you want to set everything up by yourself, please move to the DIY path.

The webpack is also already configured, so you can just use the npm run build command to build your application. Whenever you want to check anything in the browser, save the changes and run the build again. Then, refresh the page in your browser (remember to turn off caching, so that new changes are displayed instantly). At this stage, you can move to the Creating a plugin section of this guide.

Once we create a new instance of the ButtonView, we will be able to customize it by setting its properties. We will create a label, which will be visible on the button thanks to the withText property.

Learn by coding! We are going to develop a timestamp plugin that inserts current date and time into the editing area of CKEditor 4 at the caret position. The timestamp will be added after the user clicks a dedicated toolbar button.

Inside the newly created timestamp folder we are going to place the plugin.js file that will contain the plugin logic. Apart from that, since we will also need a toolbar icon for our plugin, we are going to add the icons folder and subsequently place the timestamp.png file inside.

It is customary for CKEditor 4 plugins to define an editor command that performs an action associated with them. The command should be defined inside the init function in order to be created upon the initialization of a CKEditor 4 instance.

The most important part of the plugin functionality is to insert the HTML code into the document. To do this,

we will use the editor.insertHtml method. This method

can be used to insert arbitrary HTML code into the document, so with a bit of tweaking

you can customize the timestamp plugin code to add other HTML elements into the

CKEditor 4 editing area.

Note: The exact position depends on the indexes defined by other buttons available in your toolbar, so it may take some experimenting with index values to create a perfect button sequence within a group.

Please note that since CKEditor 4.1 all editor plugins that create content should be integrated with Advanced Content Filter (ACF).

In this case the plugin only inserts content that is usually allowed in default editor installations (the element), but if you want to customize it and insert elements that are not allowed by the configuration, you need to either set config.allowedContent = true; in order to disable content filtering or integrate your plugin with ACF. For more information, please refer to the official Advanced Content Filter integration guide.

Congratulations! You have just created a valid CKEditor 4 plugin in under 20 lines of code! Since the editor.insertHtml method can be used to add arbitrary HTML code to the document, you can replace the timestamp logic with your own customized code in order to insert other types of content into your document.

The advantage of modify a build is that you no longer need to configure anything whenever a CKEditor instance is created, since everything has already been built with the desired settings. Also, the client app does not need to do a new distribution with, for instance, Webpack, importing code.

I do not use Git/GitHub in my development process, so I downloaded the ckeditor5-build-classic zip file from this Git repository, and I moved the inside contents to a desired folder. Using visual studio code, I opened the folder as a project, and started to manipulate it following the same procedures described in the mentioned tutorial:

And again the same problems are shown. Ah! Also, something strange happened. I have already said that I properly performed the installation of the CKeditor 5 alignment plugin. I have even shown how this was done. After all this problem, I tried to install the alignment plugin locally. I downloaded it from repository, and I did the same installation via link and also file. With this approach, the plugin mysteriously gave me ckeditor-duplicated-modules problem, as previously mentioned.

I don't know exactly how it would be the right way to install this plugin from CKEditor 5 itself locally without having to download it from the internet (with npm install from npm repository). I am well aware that I am doing something wrong, but I cannot identify what it is. I would appreciate if anyone could give me tips, alternatives, and of course, maybe a solution. I've been trying for a few days now, and I don't know what I can and can't do anymore. I would be really grateful if someone could help me.

Maybe it is just wording, but you shouldn't have to "install" your custom plugin. Simply add your plugin info to the \src\ckeditor.js file (the import, the builtinPlugins[], the toolbar [] etc). Then do npm run build and it will include it in the \build\ckeditor.js

The online build tool has you download a .zip and what I did was overwrote my forked project files with the ones form the zip. I built, uploaded, etc. Make note that the config for the toolbar is inside the sample/index.html if you don't add that then you won't see your toolbar.

I wanted to add the "source editing" plugin which doesn't seem supported (??) What I did was manually snagged the source-editing code from the ckeditor5 main git (all the plugins are listed at the bottom) then pasted that code into my project and imported from that folder. This is all a bit chaotic and it's not suitable for teams BUT IT WORKS - good luck

Before jumping headfirst into CKEditor, consider the outcome you're hoping to achieve and whether it needs to be in the text editor, or if it could be applied when rendering the text. For the latter, an easier solution may be a text filter. Text filters don't affect the editor preview, but if the logic is consistent, it can automate lots of adjustments such as:

Your package manager can be either NPM or Yarn, but the files must be compiled with Webpack. For CKEditor plugins, we need a compiler that can support a Dynamic-link Library (DLL), and as of this writing only Webpack offers this. So what are DLL's and why do we need them?

Dynamic-link Library is a concept borrowed from Microsoft that allows us to use an external library's API without including that library in our compiled code. DLL's in Javascript are represented as "manifest" JSON files that define the structure of a library: what classes and methods are exported under what namespaces.

With a CKEditor 5 DLL configured in my compiler, I can extend the CKEditor5's core Plugin class without adding the entire core library to my compiled code. Not only is this convenient: faster compiling with smaller compiled files, it is required! Because CKEditor5 is already instantiated in the text editor, any attempt to re-instantiate it with a plugin will throw a duplicated module error.

This isn't unique to Drupal either; all CKEditor plugins need to work inside a pre-existing ecosystem, only adding what's necessary. DLL's allow us to tell the compiler which resources will already be available when our plugin is activated, so the plugin can be applied without conflicts.

We add ckeditor5 as a dev dependency to access the CKEditor 5 DLL's. Be careful depending on libraries in the @ckeditor namespace as it can result in the duplicated module error discussed above if that code has already been instantiated in the text editor.

The beauty of the file structure setup above, is that it keeps our compiling configuration clean and independent from the number of custom plugins and their names. Our compiler can scan the js/ckeditor5 directory for plugins and then compile each plugin folder as a single file. You can look at Drupal's CKEditor5 Webpack configuration as an example.

Primarily the admin library tells Drupal what icon your toolbar button should use along with any other styling preferences. Note that this is separate from the actual CKEditor interface set up in your Javascript plugin. Drupal does not parse your CKEditor JS for those styles, so we explicitly set them here for any Drupal admin forms.

On the CKEditor side we describe the plugins we want to add with the format file.class, where "file" is the name of the compiled Javascript file and "class" is the class name of the CKEditor Plugin object exported in your index.js file. Optionally, you can declare editor config within this section using the config key.

On the Drupal side we declare the library containing the JS as well as the optional admin library. We also describe our custom toolbar items and the HTML elements that are required for the plugin to function. The latter is used by Drupal's "Limit Allowed HTML" filter, which will automatically allow these required elements when we add the custom toolbar item to an editor. If the toolbar item requires a configuration form inside the text-editor form or dynamic configuration, then a PHP class can be passed using the class key to provide that logic. This PHP class must have a namespace in the pattern \Drupal\module_name\Plugin\CKEditor5Plugin\class_name.

I'm looking for some information on how to add custom buttons to the CKEditor interface. Ideally I want to add a drop down list of values, or something that calls a javascript popup that then interacts with the editor.

Also: There is a different version of CK editor in Kentico 7 and Kentico 8 and each version might require a different approach. But in general both versions support adding plugins and each plugin can add controls into the editor tool bar.

3a8082e126