CKEditor configuration examples

This page shows how to achieve common CKEditor customizations via configuration.

Remove the 'Source' button

Prevent users from editing the HTML source by removing the CKEditor plugins for source mode editing.

ckeditor.config.overlayed.json:

{
  removePlugins: 'sourcearea,codemirror'
}

Render the editing area in an iframe instead of a div

By default Hippo uses the CKEditor plugin 'divarea' to render each editing area in a div instead of an iframe. Using divs makes the DOM lighter and results in  better performance when many editors are instantiated (e.g. with big document types or many open documents). However, some CKEditor customizations only work when the editing area is rendered in an iframe.

Use the following CKEditor configuration to render the editing area in an iframe instead of a div:

ckeditor.config.overlayed.json:

{
  removePlugins: 'divarea',
  extraPlugins: 'wysiwygarea'
}

This configuration will break the default styling of the HTML fields because the default CSS rules are scoped to '.cke_wysiwyg_div.cke_editable' (so they only apply to the div). Fix it by including your own copy of the default styles that do not scope the CSS rules to these classes.

Enable the 'forms' plugin

To enable the forms plugin, the CKEditor instance has to be running inside an iframe. This is because the HTML specification does not allow nested form elements and (unfortunately) the CMS document editor is already a form on it's own.

First we need to render the editing area in an iframe, see the previous example. Next we use the following configuration snippet to enable the 'forms' plugin and add it's buttons to the toolbar.

ckeditor.config.appended.json:

{
  plugins: 'forms',
  toolbarGroups: [
    { name: 'forms' }
  ]
}

Enable full page HTML editing

To enable editing of full HTML pages (e.g. including html, head, body, etc.), render the editing area in an iframe instead of a div (see above). Also enable full page editing in the CKEditor configuration.

ckeditor.config.overlayed.json:

{
  fullPage: true,
  removePlugins: 'divarea', 
  extraPlugins: 'wysiwygarea'
}

If additional tags in the HTML head are needed (e.g. title, link, etc.) the HTML cleaner configuration (both client-side and server-side) needs to be adjusted. It's also worthwhile to include the Document Properties CKEditor Plugin in the project. That plugin is not part of the Hippo CKEditor distribution, but can be added to a project in the same way as a custom CKEditor plugin.

Disable the CKEditor context menu

To use the browser's context menu instead of the CKEditor-specific one, render the editing area in an iframe instead of a div (see above). Also remove the CKEditor plugins that trigger the context menu.

ckeditor.config.overlayed.json:

{
  removePlugins: 'divarea,liststyle,tabletools,tableresize,contextmenu',
  extraPlugins: 'wysiwygarea'
}

Enable the Language plugin

The CKEditor Language plugin ships with Hippo CMS, but is not enabled by default. Its buttons are part of the 'bidi' toolbar group, which is also not enabled by default. So to enable the Language plugin, both the plugin and the 'bidi' toolbar group have to be added.

ckeditor.config.appended.json:

{
  extraPlugins: 'language', 
  toolbarGroups: [
    { name: 'bidi' } 
  ] 
}

Disable automatic paragraphs

CKEditor by default adds paragraph tags (<p></p>) around a line of text after the user presses the Enter key. The following configuration changes this behavior to add a line break (<br/>) instead: 

ckeditor.config.overlayed.json:

{
  enterMode: 2,
  autoParagraph: false
}

Allow q and cite tags

CKEditor by default only allows HTML tags and attributes associated with a configured plugin. Additional tags can be allowed through the extraAllowedContent configuration property. A typical use case is authors manually adding HTML tags in HTML source mode without using a plugin. The following example configuration allows use of the q tag and the cite tag with class myclass:

ckeditor.config.appended.json:

{
  extraAllowedContent: 'q cite(myclass)'
}

Note that q and cite (including the class attribute) should also be added to the server-side filteringHtmlCleanerService whitelist.