CoreMedia Studio Manual, Version 7.5.45-10
7.4.5. Customizing RichText Property Fields | 7.4.5.3. Adding Custom RichText Style Classes

You can add custom richtext style classes to the CKEditor. Style classes can be applied to block elements (for example, p) or inline elements (for example, span). Moreover, you can define groups of style classes allowing only one style class of that group to be set at a time. To define own style class groups, you have to add them via the customizeCKEditorPlugin, using its classGroups attribute of the config object as shown in the following code listing.

	Warning
	The group name must not contain hyphens.

Note, that when you apply any configuration as described in the listing, this will overwrite the default configuration in the product, rather than appending to it. Thus, you will typically want to re-add the defaults in your custom configuration - this is shown in the listing below, too.

<editor:studioPlugin>
  <ui:rules>
    <ui:richTextArea>
      <plugins>
        <ui:customizeCKEditorPlugin>
          <ui:config>
            <exml:object classGroups="{{
            'box' : {  /* name of the style class group */
              blockElements:'p',  /* block element(s) to which this */
              styleClasses: [     /* group should be applied */
                 'box--test-1',
                 'box--test-2'
              ]
            },
             /* re-add default style class group definitions  */
            'p' : {
              blockElements:'p',
              styleClasses: [
                 'p--heading-1',
                 'p--heading-2',
                 'p--heading-3'
              ]
            },
            'align' : {
              blockElements:'p',
              styleClasses: [
                 'align--left',
                 'align--right',
                 'align--center',
                 'align--justify'
              ]
            }
          }}"/>
          </ui:config>
        </ui:customizeCKEditorPlugin>
      </plugins>
    </ui:richTextArea>
  </ui:rules>
</editor:studioPlugin>

The blockElements attribute is used to define which block elements the style should be applied to. Given the current cursor position when the respective command is invoked, the system will walk the DOM hierarchy upwards until it finds a block element whose name matches the one given in the blockElements attribute. The attribute may also contain an array of element names if the style class can be applied to different elements - in this case, the style will be applied to the first element found that matches any of the element names given. If you omit the attribute, the style group definition is treated as an inline style.

The styleClasses attribute is used to set an array of style class names. The naming format is up to you, but the "--" syntax given in the example is the best practice.

To visualize a custom style in CKEditor, you need to add the respective CSS rules. As the CKEditor in the Studio is using a div container instead of an iframe you cannot use the contentCss configuration of the CKEditor, but have to load the CSS rules directly into the Studio (see the section called “Load external resources”). Use coremedia-richtext-1.0.css as a reference on how to write the CSS rules so that they only apply to the CKEditor.

The command names necessary to apply the style classes to selected text will be style_<classGroupName>_<styleClassName>. The command name to remove the style class will be style_<classGroupName>__remove. Those commands can be added to the richTextPropertyField via the addItemsPlugin as shown in the next code listing.

<editor:richTextPropertyField>
  <plugins>
    <ui:addItemsPlugin recursive="true">
      <ui:items>
        <button text="box">
          <menu>
            <menu>
              <items>
                <acme:boxButton text="test 1" richtextcommand="style_box_box--test-1"/>
                <acme:boxButton text="test 2" richtextcommand="style_box_box--test-2"/>
                <menuseparator/>
                <acme:boxButton text="remove box style" richtextcommand="style_box__remove"/>
              </items>
            </menu>
          </menu>
        </button>
      </ui:items>
      <ui:after>
        <component itemId="{...}"/>
      </ui:after>
    </ui:addItemsPlugin>
  </plugins>
</editor:richTextPropertyField>

In this example, the BoxButton is used as a wrapper around the richtext action using the mentioned commands. It is defined in a BoxButton.exml file.

<?xml version="1.0" encoding="UTF-8"?>
<exml:component xmlns:exml="http://www.jangaroo.net/exml/0.8"
                xmlns="exml:ext.config"
                xmlns:ui="exml:com.coremedia.ui.config">
  <exml:cfg name="richtextcommand" type="String"></exml:cfg>
  <menucheckitem group="box">
    <baseAction>
      <ui:richTextAction commandName="{config.richtextcommand}"/>
    </baseAction>
  </menucheckitem>
</exml:component>