Using CKEditor Plugins in Drupal 8

CKEditor is well-known software with a big community behind it and it already has a ton of useful plugins ready to be used. It is the WYSIWYG text editor which ships with Drupal 8 core.

Unfortunately, the many plugins provided by the CKEditor community can't be used directly in the CKEditor that comes with Drupal 8. It is necessary to let Drupal know that we are going to add a new button to the CKEditor.

Why Drupal needs to know about our plugins

Drupal allows us to create different text formats, where depending on the role of the user (and so what text formats they have available) they can use different HTML tags in the content. Also, we can decide if the text format will use the CKEditor at all and, if it does, which buttons will be available for that text format.

That is why Drupal needs to know about any new button, so it can build the correct configuration per text format.

Adding a new button to CKEditor

We are going to add the Media Embed plugin, which adds a button to our editor that opens a dialog where you can paste an embed code from YouTube, Vimeo, and other providers of online video hosting.

First of all, let's create a new module which will contain the code of this new button, so inside the /modules/contrib/ folder let's create a folder called wysiwyg_mediaembed. (If you're not intending to share your module, you should put it in /modules/custom/— but please share your modules, especially ones making CKEditor plugins available to Drupal!)

cd modules/contrib/
mkdir wysiwyg_mediaembed

And inside let's create the info file: wysiwyg_mediaembed.info.yml

name: CKEditor Media Embed Button (wysiwyg_mediaembed)
type: module
description: "Adds the Media Embed Button plugin to CKEditor."
package: CKEditor
core: '8.x'
dependencies:
  - ckeditor

Adding this file will Drupal allows us to install the module, if you want to read more about how to create a custom module, you can read about it here.

Once we have our info file we just need to create a Drupal plugin which will give info to the CKEditor about this new plugin, we do that creating the following class:

touch src/Plugin/CkEditorPlugin/MediaEmbedButton.php

With this content:

namespace Drupal\wysiwyg_mediaembed\Plugin\CKEditorPlugin;

use Drupal\ckeditor\CKEditorPluginBase;
use Drupal\editor\Entity\Editor;

/**
 * Defines the "wysiwyg_mediaembed" plugin.
 *
 * @CKEditorPlugin(
 *   id = "mediaembed",
 *   label = @Translation("CKEditor Media Embed Button")
 * )
 */
class MediaEmbedButton extends CKEditorPluginBase {

  /**
   * Get path to library folder.
   * The path where the library is, usually all the libraries are
   * inside the '/libraries/' folder in the Drupal root.
   */
  public function getLibraryPath() {
    $path = '/libraries/mediaembed';
    return $path;
  }

  /**
   * {@inheritdoc}
   * Which other plugins require our plugin, in our case none.
   */
  public function getDependencies(Editor $editor) {
    return [];
  }

  /**
   * {@inheritdoc}
   * The path where CKEditor will look for our plugin.
   */
  public function getFile() {
    return $this->getLibraryPath() . '/plugin.js';
  }

  /**
   * {@inheritdoc}
   *
   *  We can provide extra configuration if our plugin requires
   *  it, in our case we no need it.
   */
  public function getConfig(Editor $editor) {
    return [];
  }

  /**
   * {@inheritdoc}
   * Where Drupal will look for the image of the button.
   */
  public function getButtons() {
    $path = $this->getLibraryPath();
    return [
      'MediaEmbed' => [
        'label' => $this->t('Media Embed'),
        'image' => $path . '/icons/mediaembed.png',
      ],
    ];
  }
}

The class's code is pretty straightforward: it is just a matter of letting Drupal know where the library is and where the button image is and that's it.

The rest is just download the library and put it in the correct place and activate the module. If all went ok we will see our new button in the Drupal Text Format Page (usually at: /admin/config/content/formats).

This module was ported because we needed it in a project, so if you want to know how this code looks all together, you can download the module from here.

Now that you know how to port a CKEditor plugin to Drupal 8 the next time you can save time using Drupal Console with the following command:

drupal generate:plugin:ckeditorbutton

What CKEditor plugin are you going to port?