RSS

How to install CKEditor plugins in Drupal 8

03/20/2017 - 09:45

Step 1: Know your environment

I used Drupal 8.2.7 for this blog post demonstration.

You need to find out which CKEditor version your Drupal is using in order to download the appropriate version of the plugin. There are several ways to find out your CKEditor version:

Find the ckeditor.js file inside Drupal code and search for "version." You will find it beside the "timestamp".
Go to a page on your site that has a CKEditor, open your browser inspector, and find the ckeditor.js file as shown below:

Step 2: Download your CKEditor plugin

Update: Please read first Managing CKEditor plugins using composer, you may not need all the steps described below.

For the purpose of this demonstration we are going to install the Div Container Manager which adds a toolbar button that allows for easy insertion of div in your code. Here are the steps to follow:

On the plugins page check for the right version to download for your CKEditor. In our case version 4.5.11 is right.
Unzip the file and place the resulting folder inside the libraries folder on your Drupal root directory (you may have to create the libraries folder). You can also place the plugin folder inside your custom module if you like.

Step 3: Create your custom module

We are going to need a module for our skeleton for the Drupal CKEditor plugin, so lets create our own.

Create a module named ckeditor_div:
- Inside ckeditor_div.module you only need the opening php tag (<?php)
- Inside ckeditor_div.info.yml add the following code.
```
name: CKEditor Div Container Manager
type: module
description: Adds a Div toolbar button.
core: 8.x
package: CKEditor
dependencies:
  - ckeditor
```
Save all your files and go back to the console.

Step 4: Create the CKEditor Plugin

We are going to use the Drupal Console for our example. If you don't have it installed you will ended up seeing the following screen -- don't panic, and follow the steps indicated by the error:

Next we are going to use the command generate:plugin:ckeditorbutton, if you skip step 3 and try to use a nonexistent module on this wizard an error like this will be displayed:

Run drupal generate:plugin:ckeditorbutton.
For module name use the module we just created "ckeditor_div".
For plugin class name I used "Div", which is a capitalized version of the first argument of CKEDITOR.plugins.add method inside the plugin.js div library.
For plugin label I used "Create Div Container", which is the label value from editor.ui.addButton method from the plugin.js file.
The instructions for plugin ID are very clear, "div" is the value you are looking for in this case.
The instructions for button name are also clear, use "CreateDiv" in this step.
The button icon path is going to require further adjustments, for now add "libraries/div/icons/creatediv.png".
Answer yes to the final question and make sure your console output looks similar to mine:

We are almost there, but as I mentioned before the icon path is going to require further adjustments:

In your text editor open ckeditor_div/src/Plugin/CKEditorPlugin/Div.php
Locate function getButtons and update your code to look like the image below:
Locate function getFiles and update your code to looks like the image below:
Save the file.

Step 5: Enable module and configure CKEditor

We are almost there, here are the final steps:

Enable the module.
Go to Administration > Configuration > Content authoring, and click on the Configure button for the Text Format you want to change.
At this point you should be able to see the Div button like in the image below:
Drag the Div button to the desired position on the toolbar, and save the configuration.

That's all, now when you go to a page with a CKEditor, such as /node/add/page, your Div button will be visible under the text format that you have configured, as below:

PS: If your button is not visible while editing a node but it is visible in the configuration file, that means that the value you have on the getButtons() function doesn't match with the values from plugin.js. This got me back and forth for a while. Also the key on the returned array needs to match the icon's file name, take a look at the screen-shot above (CreateDiv key match creatediv.png file name). This got me back and forth for a while.

How to install CKEditor plugins in Drupal 8