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.