CKEditor plugins

The core of CKEditor can be extended with many plugins. Each plugin has a unique all-lowercase name that is used to reference the plugin in the CKEditor configuration.

Table of contents

• Available plugins
• Add an existing CKEditor plugin
• Remove an existing CKEditor plugin
• Add a custom CKEditor plugin
  • Example: timestamp plugin
• CKEditor plugin that opens a Wicket dialog

Available plugins

The following CKEditor plugins ship with Bloomreach Experience Manager by default:

1 The 'forms' plugin requires the CKEditor instance to run in an iframe instead of a div, please see the example configuration on how to set this up correctly.

2 Explicitly enabled by the system

3 Explicitly disabled by the system

Runtime debugging

The names of all available plugins can also be retrieved at runtime:

1. Login to Bloomreach Experience Manager using Chrome or Firefox
2. Edit a document type that contains an HTML field
3. Open the Chrome dev tools or Firebug
4. Execute the following JavaScript one-liner:

   Object.keys(CKEDITOR.plugins.registered).sort()

Similarly, it is possible to retrieve the list of plugins used by a specific editor instance:

1. Print the map of all CKEditor instances to find the name of the editor instance to inspect:

   CKEDITOR.instances

2. List all plugins in a specific instance, for example 'editor123':

   Object.keys(CKEDITOR.instances.editor123.plugins).sort()

Add an existing CKEditor plugin

To add a CKEditor plugin that is already available in Bloomreach Experience Manager, use the CKEditor configuration property 'extraPlugins'. For example, to add the 'About' plugin:

ckeditor.config.overlayed.json:

{
  extraPlugins: 'about'
}

A plugin may add one or more buttons to toolbar groups that are not shown by default. In that case, also add these toolbar groups. For example, to show the 'About' button in rich text fields, also add the following configuration:

ckeditor.config.appended.json:

{
  toolbarGroups: [
    { name: 'about' }
  ]
}

Remove an existing CKEditor plugin

To remove a CKEditor plugin that is included by default, use the CKEditor configuration property ' removePlugins'. For example, to remove the 'styles' combo box, add the following configuration:

ckeditor.config.overlayed.json:

{
  removePlugins: 'stylescombo'
}

Add a custom CKEditor plugin

Custom CKEditor plugins can be located in any .jar file that is packaged with the 'cms' application in your project. The easiest way to include them is to add them to the 'cms' artifact itself.

The source code of all custom CKEditor plugins must be placed under:

src/main/resources/ckeditor/plugins/ 

Each plugin has its own sub-directory. The name of the sub-directory is the name by which the plugin is referred to in the CKEditor configuration. Each plugin consist of main 'plugin.js' file that is loaded by CKEditor, and optionally more files and icons.

In production, the CMS uses an 'optimized' version of the CKEditor sources (i.e. minified, concatenated, one big sprint with all icons, etc.). These optimized sources are loaded from the directory src/main/resources/ckeditor/optimized. Custom plugins should therefore also generate a version of their source code that is put in the subdirectory 'optimized' and used together with the optimized CKEditor sources. Optimizing a few small custom plugins usually does not gain much performance, so the easiest way is to simply copy the sources with the Maven resources plugin (see the example below).

Example: timestamp plugin

The CKEditor developer's guide describes an example CKEditor plugin called 'timestamp'. Perform the following steps to add this timestamp plugin to the archetype-created project:

1. Download the source code and copy the tutorial-timestamp/timestamp in the directory cms/src/main/resources/ckeditor/plugins. The final file structure should be as follows:

   cms/
       src/
           main/
               resources/
                   ckeditor/
                       plugins/
                           timestamp/
                               icons/
                                   timestamp.png
                               plugin.js

2. To use a copy of the sources as an optimized version, add the following to the build/plugins section in the file cms/pom.xml:

   <build>
     <plugins>
       ...
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-resources-plugin</artifactId>
         <executions>
           <execution>
             <id>create-optimized-resources</id>
             <phase>generate-resources</phase>
             <goals>
               <goal>copy-resources</goal>
             </goals>
             <configuration>
               <outputDirectory>${project.build.directory}/classes/ckeditor/optimized</outputDirectory>
               <resources>
                 <resource>
                   <directory>${basedir}/src/main/resources/ckeditor</directory>
                 </resource>
               </resources>
             </configuration>
           </execution>
         </executions>
       </plugin>
       ...
     </plugins>
   </build>

3. Build the project and start it:

   mvn clean verify
   mvn -Pcargo.run

4. Login to the CMS as 'admin' and edit the 'newsdocument' type in the document type editor (To The Documents > Configuration > myproject > newsdocument > Edit)

5. Select the 'Body' field and add the 'timestamp' plugin to the overlayed CKEditor configuration:

   ckeditor.config.overlayed.json:

   {
     extraPlugins: 'timestamp'
   }
   

The 'timestamp' icon should now be visible in toolbar of the editor for the 'Body' field.

Follow the Simple CKEditor Plugin Tutorial to learn more about creating CKEditor plugins.

CKEditor plugin that opens a Wicket dialog

A custom CKEditor plugin can also open a Wicket dialog in Bloomreach Experience Manager. Such a plugin requires two things:

1. a CKEditor plugin for the client-side logic and UI.
2. a custom CKEditorNodePlugin Java class that creates a CKEditorPanel class with an additional CKEditorPanelExtension.

A good example of such a plugin is the 'hippopicker' plugin in the CMS. This plugin adds the 'image' and 'internal link' buttons that open the Bloomreach Experience Manager image picker and Bloomreach Experience Manager document picker, respectively (which are both Wicket dialogs). Each CKEditor field is rendered by the CKEditorPanel class. The server-side Wicket behavior for the hippopicker plugin is added by default to the CKEditorPanel by the CKEditorNodePlugin. To get your own server-side behavior in there too, create your own class that extends CKEditorNodePlugin. First add the following dependency to your cms pom.xml (or the pom.xml of another artifact that will be included in the cms war file):

<dependency>
  <groupId>org.onehippo.cms7</groupId>
  <artifactId>hippo-cms-richtext-ckeditor-frontend</artifactId>
</dependency>

The custom plugin class should override the createEditPanel method and add an extra CKEditorPanelExtension to the returned CKEditorPanel. For example:

public class MyCKEditorNodePlugin extends CKEditorNodePlugin {

    @Override
    protected CKEditorPanel createEditPanel(String id, String editorConfigJson) {
        CKEditorPanel panel = super.createEditPanel(id, editorConfigJson);
        panel.addExtension(new MyCKEditorPanelExtension(...));
        return panel;
    }
}

The MyCKEditorPanelExtension can then add the necessary Wicket behaviors that open your picker, and add the Ajax URL to open this picker to the editorConfig JSON object that will be provided to the client-side code. The client-side can then POST the Ajax URL to open the server-side picker. Vice-versa, the server-side can render some JavaScript that invokes a CKEditor command when the picker is closed (see the existing code for details).

The last thing to do is to use your own plugin class instead of the default one:

/hippo:namespaces/hippostd/html/editor:templates/_default_/root
- plugin.class = org.example.MyCKEditorNodePlugin

Visual Editor

A plugin that opens a Wicket dialog cannot be used in HTML fields in the Visual Editor. The plugin code should therefore only initialize itself when the editor is loaded in a Wicket context:

CKEDITOR.plugins.add('mywicketbasedplugin', {
  init: function (editor) {
    if (window.Wicket) {
      // initialize plugin
    }
  }
}

Another option is to not use Wicket at all. For example, let your plugin use CKEditor UI widgets only and let it call a custom REST API by creating a repository JAX-RS service.