Author: Edit Olah

Create a CKEditor plugin using Drupal’s Wysiwyg module

Drupal custom module - WYSIWYG - block quotation

How to take control over the HTML markup in the WYSIWYG editor without the risk of site editors accidentally messing up the markup?

Most companies, with a website that is built on a content management system, like giving their site editors the power of inputting nested HTML elements with the right CSS classes through a WYSIWYG text editor.

Here is how to create a CKEditor plugin - tapping into the goodness of Drupal’s Wysiwyg module - to add a button to the WYSIWYG editor that allows the user to add a block quotation with specific HTML markup.

Mentor:
Chris Maiden

This solution makes use of the functions offered by the Wysiwyg module. I have put together an easy-to-follow step-by-step guide. The CKEditor plugin inserts specific HTML markup into the WYSIWYG text editor area or wraps the selected text into it.

Prerequisites:

  • Version of Drupal: Drupal 7
  • Modules and other requirements:
  • Hierarchy of directories:
    d -| sites
    d ---| all
    d -----| modules
    d -------| custom
    d ---------| custom_wysiwyg
      -----------| custom_wysiwyg.info
      -----------| custom_wysiwyg.module

- ! TIP ! -

Solution for ‘CKEditor version could not be detected’ error that occurs during setting up the CKeditor library.

When setting up the Wysiwyg module with CKEditor library, during the configuration at 'admin/config/content/wysiwyg', there is usually an error message saying:
'The version of CKEditor could not be detected.'

For a solution check out the comments for this issue on drupal.org.

GitHub Gist:

Custom WYSIWYG plugin for Drupal 7 - blockquote

Steps:

1. Create a custom module (In this example, I will call it: ‘custom_wysiwyg’).

1.1 Create the folder structure with the necessary files (see above).

1.2 In the ‘custom_wysiwyg.info’ file, you need these details:

name = MY CUSTOM WYSIWYG
description = Customisation of the WYSIWYG editor.
core = 7.x
package = My project

In the ‘custom_wysiwyg.module’ file, you need to register the directory that contains the plugin definitions:

<?php
/**
 * @file
 * Drupal hook implementations.
 */

/**
 * Implements hook_wysiwyg_include_directory().
 */
function custom_wysiwyg_wysiwyg_include_directory($type) {
  return $type;
}

The ‘hook_wysiwyg_include_directory’ function takes advantage of the logic in the ‘wysiwyg.module’ and the ‘wysiwyg.api.php’ files in ‘sites/all/modules/contrib/wysiwyg’. You need this hook to register the directory containing the plugin definitions. See the steps broken down in the ‘wysiwyg.api.php’ file.



2. Create your plugin.

2.1 Create a new directory called ‘plugins’.

d -| sites
d ---| all
d -----| modules
d -------| custom
d ---------| custom_wysiwyg
d -----------| plugins
d -------------| blockquote
  -------------| blockquote.inc
  -----------| custom_wysiwyg.info
  -----------| custom_wysiwyg.module

Choose a name for your plugin. (In this example, let’s call it: ‘blockquote’.) Create a folder called ‘blockquote’ and the ‘blockquote.inc’ file inside the ‘plugins’ directory. Create the ‘.inc’ file.
Into the ‘.inc’ file, goes the following code:

<?php

/**
 * Implements hook_INCLUDE_plugin().
 */
function custom_wysiwyg_blockquote_plugin() {
  $plugins['blockquote'] = array(
    'title' => t('My blockquote'),
    'icon path' => drupal_get_path('module', 'custom_wysiwyg') . '/plugins/blockquote/icons',
    'icon file' => 'blockquote.png',
    'icon title' => t('Insert Blockquote'),
    'js path' => drupal_get_path('module', 'custom_wysiwyg') . '/plugins/blockquote',
    'js file' => 'plugin.js',
    'settings' => array(),
  );

  return $plugins;
}

This is where you tell Drupal to include your cross-editor plugin using the Wysiwyg module’s ‘hook_INCLUDE_plugin()’, which specifies meta information to define your plugin. (Find more information about how this function works in /sites/all/modules/contrib/wysiwyg/wysiwyg.api.php.)

2.2 Create your plugin template.

d -| sites
d ---| all
d -----| modules
d -------| custom
d ---------| custom_wysiwyg
d -----------| plugins
d -------------| blockquote
d ---------------| icons
  -----------------| blockquote.png
  ---------------| plugin.js
  -------------| blockquote.inc
  -----------| custom_wysiwyg.info
  -----------| custom_wysiwyg.module

Inside the ‘blockquote’ directory, create a folder (‘icons’) for the icon you would like to appear on the button in the WYSIWYG toolbar; and create a ‘.js’ file called ‘plugin’. In the ‘plugin.js’ file, you need to put the following JavaScript code:

Drupal.wysiwyg.plugins.blockquote = {
  invoke: function (data, settings, instanceId) {
    if (data.format == 'html') {
      if (data.content) {
        var content = '<blockquote class="block-quote__wrap clearfix"><span class="block-quote__start">“</span><p>' + data.content + '</p></blockquote>';
      }
      else {
        var content = '<blockquote class="block-quote__wrap clearfix"><span class="block-quote__start">“</span><p></p></blockquote>';
      }
    }
    if (typeof content != 'undefined') {
      Drupal.wysiwyg.instances[instanceId].insert(content);
    }
  }
};

This is where you can specify the HTML.

Enable your new button by going to ‘Administration >> Configuration >> Content authoring >> Wysiwyg profiles >> your relevant wysiwyg profile’, ‘Buttons and Plugins’ section and adding ‘Blockquote’ to the selected buttons. Don’t forget to save your configuration.

You should now have a button in the WYSIWYG toolbar that does exactly what you need:

Screenshot of WYSIWYG editor with the new button in the toolbar. Make sure that the necessary HTML tags are included among the 'Allowed HTML tags!

You should be able to switch on the ‘blockquote’ mode by clicking your new button in the WYSIWYG toolbar. This will insert your HTML when you click into the text editing area with the cursor in between the <p></p> tag pair, waiting for you to input the content.

Screenshot of WYSIWYG editor with the blockquote styled and inserted into the WYSIWYG editor's text area.

The markup should look like this:

<blockquote class="block-quote__wrap clearfix">This is a blockquote.</blockquote>

Resources:

Wysiwyg module

CKEditor library

Solution for ‘CKEditor version could not be detected’

DrupalContrib - wysiwyg.api.php

Related blog posts

  • Create a CKEditor plugin powered by the CKEditor API

    Create a CKEditor plugin powered by the CKEditor API

    Drupal custom module - WYSIWYG - block quotation

    How to create a WYSIWYG plugin - tapping into the powers of the CKEditor...

    More details >>

  • Take control over the HTML markup in the WYSIWYG editor!

    Take control over the HTML markup in the WYSIWYG editor!

    Drupal custom module - WYSIWYG - accordion and 2-column section

    Custom WYSIWYG plugins for site editors to be able to click a button in...

    More details >>

Contact Edit

Get in touch

If you are interested in hiring me, please drop me an email. I would be happy to send you my up-to-date resume.

Drupal Association member
Image of Edit