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.

Config(RichTextArea, {
  plugins: [
    Config(CustomizeCKEditorPlugin, {
      ckConfig: {
        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'
            ]
          }
        }
      }
    })
  ]
})

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 multiple element names, if the style class can be applied to different elements. The names are separated by the pipe symbol "|" and the style will be applied to the first element found that matches any of the element names given. For example, blockElements:'p|td'. 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 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 Studio (see Section “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.

Config(RichTextPropertyField, {
  bindTo: config.bindTo,
  propertyName: "detailText",
  initialHeight: 200,
  plugins: [
    Config(AddItemsPlugin, {
      recursive: true,
      items: [
        Config(Separator, {
          itemId: "...",
        }),
        Config(Button, {
          text: "test",
          menu: Config(Menu, {
            items: [
              Config(BoxButton, {
                text: "test 1",
                richtextcommand: "style_box_box--text-1",
              }),
              Config(BoxButton, {
                text: "test 2",
                richtextcommand: "style_box_box--text-2",
              }),
              Config(Separator),
              Config(BoxButton, {
                text: "remove box style",
                richtextcommand: "style_box__remove",
              }),
            ],
          }),
        }),
      ],
      after: [
        Config(Component, {
          itemId: "..."
        }),
      ],
    })
  ]
})

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

interface BoxButtonConfig extends Config<RichTextMenuCheckItem>, Partial<Pick<BoxButton,
  "richtextcommand"
>> {}

class BoxButton extends RichTextMenuCheckItem {
  declare Config: BoxButtonConfig;

  static override readonly xtype: string = "com.coremedia.ui.config.boxButton";

  richtextcommand: string = null;

  constructor(config: Config<BoxButton> = null) {
    super(ConfigUtils.apply(Config(BoxButton, {
      baseAction: {
        Config(RichTextAction, {
          commandName: config.richtextcommand,
          ckEditorValueExpression: config.ckEditorValueExpression
        })
      }
    }), config));
  }
}

export default BoxButton;