RSS

How to install CKEditor plugins in Drupal 8

How to install CKEditor plugins in Drupal 8

CKEditor addons in Drupal

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:ckeditor version - browser inspector

Step 2: Download your CKEditor plugin

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.ckeditor download plugin

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:

ckeditor - no drupal console

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:

ckeditor - no module
  • 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:
ckeditor - generating plugin

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:ckeditor - getButtons

     

  • Locate function getFiles and update your code to looks like the image below:ckeditor - getFiles

     

  • 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:ckeditor - Div button on toolbar

     

  • 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:

ckeditor - final result

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.