Customize CKEditor styles - BloomReach Experience - Open Source CMS

This article covers a Hippo CMS version 12. There's an updated version available that covers our most recent release.

01-11-2018

Customize CKEditor styles

The 'styles' combo box in CKEditor can be customized as follows:

  1. Add a JavaScript file to the cms application of your project (or any .jar file packaged with that cms application) in the directory src/main/resources/ckeditor.

    For example:

    cms/src/main/resources/ckeditor/mystyles.js
  2. Define your custom styles in this JavaScript via the API method CKEDITOR.stylesSet.add, as explained at the CKEditor website.

    For example:

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

    The 'name' will be shown in the styles combo box. Both 'styles' (with CSS styles) and 'attributes' (with extra element attributes) are optional.

    Note that, while the method name CKEDITOR.stylesSet.add might imply the custom styles are added to the default styles, they actually replace the default styles completely.
  3. Let Maven create an optimized version of the mystyles.js file in in the subdirectory ckeditor/optimized. This optimized file will be used in production. The simplest solution is to copy the mystyles.js file with the maven-resources-plugin. 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-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>
    
  4. Use your custom style by setting the property stylesSet in the CKEditor configuration.

    ckeditor.config.overlayed.json:

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

Localizing style names

Custom styles should get a localized name for the CMS language of the current user. This can be achieved by defining a different stylesheet per CMS language whose name contains the locale language (e.g. 'en', 'nl', etc.).

For example:

(function() {
  "use strict";

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

The styleSet property can then use the parameter ' {language}', which will be replaced with the current CMS language when a CKEditor instance is loaded.

For example:

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

To avoid repeating the style definitions the JavaScript can be a little smarter. See the hippostyles.js file (which contains the default styles) for an example.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?