Author: Edit Olah

Create a CKEditor plugin powered by the CKEditor API

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 WYSIWYG plugin - tapping into the powers of the CKEditor API - to add a button to the WYSIWYG editor that allows the user to add a block quotation with specific HTML markup.

Mentor:
Joeri Poesen

This solution is driven by Drupal’s WYSIWYG module and the CKEditor API. This step-by-step guide shows you how to create a plugin that wraps the selected text into a specific HTML markup with a push of a button in the WYSIWYG text editor.

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

GitHub Gist:

Custom WYSIWYG plugin for Drupal 7 - CKEditor API - blockquote

Steps:

1. Create a custom module (In this example, let’s 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 will need to put this code:

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

1.3 In the ‘custom_wysiwyg.module’ file, you need add hook_wysiwyg_plugin:

<?php
/**
 * Implements hook_wysiwyg_plugin().
 */
 function custom_wysiwyg_wysiwyg_plugin($editor, $version) {
 
  switch ($editor) {
   case 'ckeditor':
	return array(
 	'my_wysiwyg_plugin' => array(
  	'path' => drupal_get_path('module', 'ucl_wysiwyg') . '/my_wysiwyg_plugin',
  	'buttons' => array(
   	'my_plugin_button' => t('Insert my Blockquote'),
  	),
  	'load' => TRUE,
 	),
	);
	break;
  }
 }

As a related article on drupal.org confirms: the above code will let the WYSIWYG module know to make your new button available, so don’t forget to enable it in the WYSIWYG profile you are using.
(Go to: /admin/config/content/wysiwyg/profile/wysiwyg_profile_in_use/edit)

As you can read it in the wysiwyg.module file:
‘Implementations of hook_wysiwyg_plugin() may execute different code for each editor. Therefore, we have to invoke those implementations for each editor, but process the resulting plugins separately for each profile.’

So you can add a new case for a different editor in the function, if you need to.



2. Create your plugin.

In this example, we are creating a plugin for a ‘blockquote’. Let’s call our plugin ‘my_wysiwyg_plugin’. Create a folder called ‘my_wysiwyg_plugin’. Inside this directory, you will need a ‘plugin.js’ file and the icon you would like to assign to your plugin in the WYSIWYG toolbar.

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

In the ‘plugin.js’ file, you define what your plugin should do for you using the JavaScript methods and events offered by the CKEditor API:

(function($) {
 CKEDITOR.plugins.add( 'my_wysiwyg_plugin', {
  icons: 'my_plugin_button',
  init: function( editor )
  {
   editor.addCommand( 'my_command', {
    exec : function( editor ) {
     //here is where we tell CKEditor what to do.
      var selected_text = editor.getSelection().getSelectedText();
          var new_element = new CKEDITOR.dom.element("blockquote");
          new_element.setAttributes({class: 'myclassname'});
          new_element.setText(selected_text);
          editor.insertElement(new_element);
        }
   });
   
   editor.ui.addButton( 'my_plugin_button', {
    label: 'Insert my Blockquote', //this is the tooltip text for the button
    command: 'my_command',
    icon: this.path + 'icons/my_plugin_button.png'
   });
  }
 });
})(jQuery);

The JavaScript will add a button to the WYSIWYG toolbar and insert a <blockquote>></blockquote> HTML tag pair with a class specified by you that will be wrapped around the selected text in the WYSIWYG editor.

The resulting HTML markup will look like this:

<blockquote class="myclassname">This is my blockquote.</blockquote>

- ! TIP ! -

When you are making changes in the ‘plugin.js’ file, force-reload the browser or clear the browser cache after every amendment to be able to see the effect of your changes.

- ! 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.

Resources:

Wysiwyg module

CKEditor library

Solution for ‘CKEditor version could not be detected’

Creating CKEditor plugin using wysiwyg hooks

Developing a custom plugin

Related blog posts

  • Create a CKEditor plugin using Drupal’s Wysiwyg module

    Create a CKEditor plugin using Drupal’s Wysiwyg module

    Drupal custom module - WYSIWYG - block quotation

    How to create a CKEditor plugin - tapping into the goodness of Drupal’s...

    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