Customize CKEditor styles - BloomReach Experience - Open Source CMS

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

12-05-2015

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.

  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?