Configuring and customizing CKEditor

  Written by The Jahia Team
 
Developers
   Estimated reading time:

CKEditor integration

This sections shows you how to customize CKEditor, the WYSIWYG rich text editor used for authoring content in Jahia. Jahia 8 includes CKEditor 4.13 embedded in React forms and uses the React pickers from Content Editor that come with the latest version of Jahia (for selecting files, folders, and content inside CKEditor).

There are different ways to customize CKEditor to fit your needs: 

  • Overriding the CKEditor configuration by loading a custom CKEditor configuration
  • Adding plugins to CKEditor 
  • Using one of the predefined CKEditor toolbars 

Overriding the CKEditor configuration

The CKEditor configuration is loaded in the following order of priority:

  1. Any configuration at the property level in your content type definition.
  2. A configuration defined in your template set.
  3. The configuration defined at the platform level.

If none of these configurations is defined, the default CKEditor configuration applies.

Configuration at the property level in content type definitions

You can define a custom configuration at the property level directly in the definition of a content type. With the following definition, the summary field of the myArticle nodetype will display the CKEditor with a minified toolbar:

[jnt:myArticle] > jnt:bigText, jmix:basicContent, jmix:editorialContent
 - summary (string, richtext[ckeditor.toolbar='Mini']) i18n

Screenshot 2020-05-05 at 15.31.32.png

You can also define the custom configuration file per field in a similar way, for example:

[bootstrap4mix:text] mixin
 - text (string, richtext[ckeditor.toolbar='Tinny',ckeditor.customConfig='$context/modules/bootstrap4-components/javascript/ckconfig.js']) i18n

The above definition will force CKEditor to use the defined configuration file when authoring content for that field.

Note: By default, CKEditor displays the toolbar depending on the permission the current user has in Jahia. A user can have Full or Basic permission and will see a Full or Basic toolbar, depending on permission they are granted. If a user has no explicit permission, the Light toolbar displays. Overriding the CKEditor toolbar definition, as in the example above, will also override this default logic.

Configuration at the template set level

By including a /javascript/ckeditor_config.js file into a template set bundle, you can extend or override the CKEditor configuration for all rich text fields in your web projects that use this template set. The format of that file is the same as CKEditor's default config.js file. For more information, see Setting CKEditor Configuration - Using the config.js File.

Configuration at the platform level 

You can customize or override the CKEditor configuration globally, by providing it in an OSGi fragment bundle whose host is the "ckeditor" bundle.

To automate the bundle packaging and deployment process, you can use the CKEditor configuration utility, which is located in the Tools Area (http://[digital-factory-server]:[port]/tools/ckeditorConfig.jsp).

ckeditor-configuration-tool.png

The tool allows you to build and download the configuration bundle or build and deploy the bundle into that Jahia instance to test the configuration immediately. The format of the provided configuration is the same as the one in the CKEditor's config.js file. For more information, see Setting CKEditor Configuration - Using the config.js File.

For example, by building and deploying the following configuration:

CKEDITOR.editorConfig = function( config ) {
    config.extraPlugins='mathjax';
    config.toolbar_Full[8]=['Image','Flash','Table','HorizontalRule','Smiley','SpecialChar','PageBreak','Mathjax'];
}

We enable the Mathematical Formulas plugin and add the corresponding button into the Full toolbar:

Screenshot 2020-05-05 at 13.30.35.png

Adding a CKEditor plugin

CKEditor is a modular framework that can be extended with many plugins. Version compatibility between CKEditor and the plugins is something to monitor to ensure a smooth integration. Please get in touch with the plugin editor if necessary. A list of the embedded plugins can be found here

To enable one of the embedded plugins, you only have to activate it in your js config, defined in any module.

Also adding any additional plugin involves only a few steps:

  • In the templateSet module, add the plugin.js under the folder: /javascript/ckeditor/plugins/<nameOfThePlugin>/plugin.js
  • In the CKEditor configuration file, add the following line to load the plugin.js file: CKEDITOR.plugins.addExternal('<nameOfThePlugin>', '/modules/nameOfYourTemplateSet/javascript/ckeditor/plugins/nameOfThePlugin/plugin.js');
  • In the config function, add your plugin to the extraPlugins variable: CKEDITOR.editorConfig = function( config ) { ... config.extraPlugins = '<nameOfThePlugin>'; ... }

That's it. The additional plugin should be available to all rich text editors inside Jahia. 

Examples

You can also provide template-set specific CKEditor configurations:

There is an example of the config file in the sample-bootstrap-templates module (ckconfg.js) that provides a custom toolbar, and defines custom styles and templates. The custom file is used in several fields from the sample-bootstrap-templates module:

Screenshot 2020-05-05 at 15.33.12.png

Toolbar definitions

The toolbar loaded in CKEditor depends on the permission of the user. There are predefined toolbars which are linked to a built-in permission in Jahia.

The predefined toolbars are: Full, Basic, Light, Mini and User. Users with:

  • the View Full WYSIWYG Editor permission see the full toolbar
  • the View Basic WYSIWYG Editor permission see the basic toolbar
  • With no explicit permission see the Light toolbar in CKEditor.

If you have an override on a property level in place, this will be loaded in priority of the toolbar according to the permission check.