Customize CKEditor Styles

You can customize the styles available in the CKEditor "styles" combo box by following these steps.

Overview

CKEditor allows you to define custom styles that appear in the styles dropdown. This configuration is managed through JavaScript files in your project and referenced in the CKEditor configuration.

Prerequisites

• Access to the cms application source code in your project.
• Familiarity with Maven build configuration.
• Basic understanding of JavaScript.

Implementation Steps

1. Add a JavaScript File for Custom Styles

Create a JavaScript file in the cms application under the src/main/resources/ckeditor directory. You can also include this file in any JAR packaged with the cms application.

Example file path:

cms/src/main/resources/ckeditor/mystyles.js

2. Define Custom Styles in JavaScript

Use the CKEDITOR.stylesSet.add API to define your custom styles. Refer to the CKEditor documentation for details.

Example:

(function () {
  "use strict";

  CKEDITOR.stylesSet.add('mystyle', [
    {
      element: 'h1',
      name: 'Blue Fancy Title',
      styles: {
        color: 'blue'
      },
      attributes: {
        class: 'fancy'
      }
    }
  ]);
}());
copy

• The name property appears in the styles combo box.
• The styles property specifies CSS styles.
• The attributes property adds HTML attributes to the element.
• Both styles and attributes are optional.

Note: Defining a custom style set with CKEDITOR.stylesSet.add replaces the default styles. It does not merge with them.

3. Optimize the JavaScript File for Production

Maven should generate an optimized version of your JavaScript file in the ckeditor/optimized subdirectory. This optimized file is used in production.

The simplest approach is to copy the file using the Maven Resources Plugin. Add the following configuration to the build/plugins section of cms/pom.xml:

<build>
  <plugins>
    ...
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-resources-plugin</artifactId>
      <executions>
        <execution>
          <id>create-optimized-ckeditor-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>
copy

4. Reference the Custom Styles in CKEditor Configuration

Set the stylesSet property in your CKEditor configuration to use your custom style set.

Example (ckeditor.config.overlayed.json):

{
    stylesSet: 'mystyle:./mystyles.js'
}

Localizing Style Names

To provide localized style names based on the CMS user's language, define separate style sets for each language. Name each style set with the locale code (such as en or nl).

Example:

(function() {
  "use strict";

  CKEDITOR.stylesSet.add('mystyle_en', {
    element: 'h1',
    name: 'Heading 1',
  });
  CKEDITOR.stylesSet.add('mystyle_nl', {
    element: 'h1',
    name: 'Kop 1',
  });
}());
copy

In your CKEditor configuration, use {language} as a placeholder. CKEditor replaces this with the current CMS language when loading the editor.

Example:

{
  stylesSet: 'mystyle_{language}:./mystyles.js'
}

To avoid duplicating style definitions, you can implement logic in your JavaScript file to generate localized sets dynamically. For reference, see the hippostyles.js file, which contains the default style definitions.

Verification

• Open the CKEditor in the CMS.
• Confirm that your custom styles appear in the styles combo box.
• If you have configured localization, verify that style names match the current CMS language.

Related Topics

• CKEditor Configuration Properties
• CKEditor Style Set Documentation
• hippostyles.js Example