close

Filter

loading table of contents...

Studio Developer Manual / Version 2301

Table Of Contents

10.2.2.5 Customizing Rich Text Toolbar

The buttons and menu items of the toolbar can be customized by applying the addItemsPlugin and removeItemsPlugin to richTextPropertyField. The item ids of the buttons and menu items provided are listed as constants in the API documentation of richTextPropertyField.

It is also possible to add a toolbar button for a custom plugin or a CKEditor 4 plugin.

When adding a new button to the toolbar and you want it to perform a CKEditor 4 command, you can use the RichTextAction with the configured command name. Commands used by default are listed as constants in the API documentation. When the new button should display a state (like the "bold" button renders as pressed when a bold text is selected), make sure to set the config option enableToggle on the button to true, or use the convenience class RichTextActionToggleButton which does just that.

Note that all RichTextActions have a mandatory config option ckEditorValueExpression. When using the RichTextMenuCheckItem or RichTextMenuItem, or if you define a button or menu item for the RichTextPropertyField toolbar or context menu yourself and they contain a RichTextAction you must set the ckEditorValueExpression config option.

When adding or extending a menu in the toolbar and the menu items should perform richTextActions for context-sensitive CKEditor 4 commands, you should use the richTextMenuCheckItem for a correct representation of the enabled and active states of the command. See the API documentation for more information.

Add the functionality into a Studio plugin that can be used in the richTextPropertyField configuration (see Section 9.3, “Studio Plugins” and especially the warning box why a separate file is necessary). The following code, included in a file CustomizeRichTextPlugin.ts, moves the italic button between the internal link and external link button and removes the heading 3 paragraph format menu from the rich text toolbar.

Config(NestedRulesPlugin, {
  rules: [
    Config(Toolbar, {
      ...ConfigUtils.append({
        plugins: [
          Config(RemoveItemsPlugin, {
            items: [
              Config(Component, {
                itemId: RichTextPropertyField.ITALIC_BUTTON_ITEM_ID,
              }),
            ]
          }),
          Config(AddItemsPlugin, {
            items: [
              Config(RichTextActionToggleButton, {
                itemId: RichTextPropertyField.ITALIC_BUTTON_ITEM_ID,
                commandName: RichTextAction.COMMAND_ITALIC
              }),
            ],
            after: [
              Config(Component, {
                itemId: RichTextPropertyField.INTERNAL_LINK_BUTTON_ITEM_ID
              })
            ]
          }),
        ],
      }),
    }),
    Config(Menu, {
      ...ConfigUtils.append({
        plugins: [
          Config(RemoveItemsPlugin, {
            items: [
              Config(Component, {
                itemId: RichTextPropertyField.PARAGRAPH_HEADING3_ITEM_ID,
              }),
            ]
          }),
        ],
      }),
    }),
  ],
}),

Example 10.33. Customizing the rich text editor toolbar


Please note that the RichTextActionToggleButton has a mandatory ckEditorValueExpression config. This config can only be omitted here, because the RichTextPropertyField's toolbar automatically adds it to all its items.

The baseAction, as in the above example, can also reference a custom action defined in a custom or CKEditor 4 plugin. In this case, the commandName of the richtextAction is the name given in the plugin definition.

You can either apply the plugin to all rich text fields or only to a specific content type. When you add it to your *StudioPlugin.ts, the plugin is applied to all rich text fields:

Config(StudioPlugin, {
  rules: [
    ...
    Config(RichTextPropertyField, {
      ...ConfigUtils.append({
        plugins: [
          Config(CustomizeRichTextPlugin)
        ]
      })
    })
  ]
})

When the plugin should only be applied to a specific rich text field, you have to add it to a specific *DocumentForm.ts file:

Config(DocumentTabPanel, {
  items: [
    Config(RichTextPropertyField, {
      propertyName: 'detailText',
      ...ConfigUtils.append({
        plugins: [
          Config(CustomizeRichTextPlugin)
        ]
      })
    })
  ]
})

Here, it is important, that you use ...ConfigUtils.append(...). Otherwise, you would remove all plugins that are already defined for this field.

You may also add a custom icon to the toolbar or use one bundled with an existing CKEditor 4 plugin. To do this, apply the addItemsPlugin as above to the richTextPropertyField. The iconButton can take the arguments iconCls, text and tooltip in order to apply and localize the custom icon. The iconCls property defines the CSS class of the icon. The icon image location and style may then be added to the css using the CSS class name defined by the iconCls.

Config(IconButton, {
    iconCls: resourceManager.getString(
      'some.namspace.MyPluginLabels', 'MyPlugin_icon'),
    tooltip: resourceManager.getString(
      'some.namspace.MyPluginLabels', 'MyPlugin_tooltip'),
    text: resourceManager.getString(
      'some.namspace.MyPluginLabels', 'MyPlugin_text')
})

Example 10.34. Adding a custom icon to the rich text editor toolbar


As in the example above, these three properties may be defined in a separate properties bundle that can be localized.

You can customize the toolbar of the TeaserOverlayPropertyField. E.g. to add an InternalLinkButton, you can create a NestedRulesPlugin as follows.

interface CustomNestedPluginConfig extends Config<NestedRulesPlugin> {
}

class CustomNestedPlugin extends NestedRulesPlugin {
  declare Config: CustomNestedPluginConfig;

  constructor(config: Config<CustomNestedPlugin> = null) {
    const field = cast(TeaserOverlayPropertyField, config.cmp.initialConfig);

    super(ConfigUtils.apply(Config(CustomNestedPlugin, {
      rules: [
        Config(FloatingToolbar, {
          ...ConfigUtils.append({
            plugins: [
              Config(AddItemsPlugin, {
                items: [
                  Config(InternalLinkButton, {
                    itemId: '...',
                    bindTo: field.bindTo,
                    forceReadOnlyValueExpression:
                      field.forceReadOnlyValueExpression,
                    plugins: [
                      Config(BindDisablePlugin, {
                        bindTo: field.bindTo,
                        forceReadOnlyValueExpression:
                          field.getRichTextButtonsDisabledVE()
                      })
                    ]
                  }),
                  ... for ExternalLinkButton and remove link button see below
                ]
              }),
            ],
          }),
        }),
      ],
    }), config));
  }
}

export default CustomNestedPlugin;

Example 10.35. Adding InternalLinkButton to the toolbar in TeaserOverlayPropertyField


To add an ExternalLinkButton and a button to remove links insert the following code in the plugin. Remember: All of these buttons have a mandatory ckEditorValueExpression config, that will be set automatically by the floating toolbar.

Config(ExternalLinkButton, {
  itemId: '...',
  bindTo: teaserOverlayPropertyField.bindTo,
  forceReadOnlyValueExpression:
    teaserOverlayPropertyField.forceReadOnlyValueExpression,
  ckEditorValueExpression:
    teaserOverlayPropertyField.getCKEditorValueExpression(),
  plugins: [
    Config(BindDisablePlugin, {
      bindTo: teaserOverlayPropertyField.bindTo,
      forceReadOnlyValueExpression:
        teaserOverlayPropertyField.getRichTextButtonsDisabledVE()
    })
  ]
})

Config(RichTextActionToggleButton, {
  itemId: '...',
  commandName: RichTextAction.COMMAND_UNLINK,
  plugins: [
    Config(BindDisablePlugin, {
      bindTo: teaserOverlayPropertyField.bindTo,
      forceReadOnlyValueExpression:
        teaserOverlayPropertyField.getRichTextButtonsDisabledVE()
    })
  ]
})

Example 10.36. Adding two more buttons to the toolbar


Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.