close

Filter

loading table of contents...

Studio Developer Manual / Version 2301

Table Of Contents

10.2.2.6 Customizing CKEditor 4 by Plugins

CKEditor 4 provides rich text editing capabilities in a browser independent way. It has a plugin-driven architecture. Plugins are JavaScript files that are loaded at the end of CKEditor 4 loading process, before the initialization and activation of CKEditor 4 instances. Plugins are named and defined in a file named plugin.js which resides under a path matching the plugin's name. Plugins may add UI features, change the behavior of existing UI components or add data manipulation features. CKEditor 4 provides automatic runtime plugin dependency management.

The custom plugin my-plugin can be added to a CoreMedia Studio project by editing the following file

my-custom-ckeditor-package/sencha/resources/ckeditor/plugins/my-plugin/plugin.js

If not already done in the parent project, the path of the plugin.js has to be configured as an additional global resource in your package. We will add a sencha/src/packageConfig.js first...

// Adding global resources to ext manifest
Ext.registerGlobalResources({
  "ckeditor.plugin.myplugin": "<@com.coremedia.cms__studio-client.my-custom-ckeditor-package>ckeditor/plugins/myplugin/plugin.js",
  ...
});

Example 10.37. Adding the packageConfig.js in the sencha/src folder


... and then add it to the jangaroo.config.js (please note that the sencha folder is omitted here):

module.exports = jangarooConfig({
  type: "code",
  autoLoad: [
    "./src/packageConfig",
    ...
  ],
  sencha: {
    name: "com.coremedia.cms__studio-client.my-custom-ckeditor-package",
    namespace: "...",
    ...
  },
});

Example 10.38. Adding the reference to the jangaroo.config.js


The content of the plugin.js may be similar to

CKEDITOR.plugins.add('my-plugin',
{
  beforeInit(editor){
    ...
  },
  init : function(editor) {
    ...
  },
  lang : [...],
  requires: [...]
});

Example 10.39. Customizing CKEditor 4


The argument passed to the add method is a so-called plugin definition whose beforeInit and init functions are called upon creation of every CKEditor 4 instance in that package. The definition may also provide the lang and requires attributes which respectively define valid languages for the plugin and a list of required plugins.

The official CKEditor 4 API documentation is available at ckeditor.com/docs/ckeditor4/latest/api/.

The custom plugin can now be registered by CKEditor 4. This is done by using the addCKEditorPluginsPlugin with your RichTextArea:

Config(RichTextArea, {
  plugins: [
    Config(AddCKEditorPluginsPlugin, {
      plugins: 'my-plguin'
    })
  ]
})

You can remove predefined plugins so that they are not loaded by CKEditor 4. This is done by using the RemoveCKEditorPluginsPlugin in your RichTextArea. To remove the CKEditor 4 plugin about, for example, add the following to your declaration:

Config(RichTextArea, {
  plugins: [
    Config(RemoveCKEditorPluginsPlugin, {
      plugins: 'about'
    })
  ]
})

The list of additional CKEditor 4 plugins loaded by CoreMedia Studio by default is documented in API documentation of RichTextArea as the constant defaultCKEditorExtraPlugins. The list of standard CKEditor 4 plugins, that are excluded by default are listed in API documentation of RichTextArea as the constant defaultCKEditorRemovePlugins.

To change other configuration options of CKEditor 4, you can use the CustomizeCKEditorPlugin with your RichTextArea. A list of CKEditor 4 configuration options can be found here: CKEditor.config For example, to instruct CKEditor 4 to add 2 spaces to the text when hitting the TAB key, use the following code:

Config(RichTextArea, {
  plugins: [
    Config(CustomizeCKEditorPlugin, {
      ckConfig: {
        tabSpaces: 2,
      }
    })
  ]
})

Example 10.40. Customizing the CKEditor 4 configuration


Items or Buttons that execute custom CKEditor 4 commands have to be added to the rich text toolbar using the AddItemsPlugin as described in Section 10.2.2.5, “Customizing Rich Text Toolbar”. This cannot be done in CKEditor 4 directly.

Styling of CKEditor 4 Dialogs

As some original CKEditor 4 dialogs are used, the styling of these dialogs had to be adjusted, so that they fit better into Studio. If you want to change the styling of CKEditor 4 dialogs there are two possible ways to do so:

  1. Using the CKEditor 4 configuration option skin (see Example 10.40, “Customizing the CKEditor 4 configuration”) and provide your own CKEditor 4 skin that overrides the dialog.css (see CKEditor 4 Skin SDK — Introduction).

    The files of the custom skin my-skin can be added to a CoreMedia Studio project by adding them to following folder:

    my-custom-ckeditor-package/sencha/resources/ckeditor/skins/my-skin/

    The path that is pointing to this skin has to be configured as an additional global resource in the project sencha/src/packageConfig.js:

                // Adding global resources to ext manifest
    Ext.registerGlobalResources({
      ...
      "ckeditor.skin.my-skin": "<@com.coremedia.cms__studio-client.my-custom-ckeditor-package>ckeditor/skins/my-skin/"
    });
              

    Example 10.41. Adding resource path of skin to sencha/src/packageConfig.js


    The sencha/src/packageConfig.js has to be referenced in the jangaroo.config.js in the package root. As all files in the sencha folder are just copied over to the build directory the reference does not have the sencha folder: src/packageConfig.js. Please see Section 10.2.2.6, “Customizing CKEditor 4 by Plugins” to learn about loading additional resources in your package.

  2. Load a custom SCSS file overriding the rules from the dialog.css of the default CKEditor 4 skin. The advantage of this approach is that you can make use of all CoreMedia SCSS variables, and you do not have to copy the complete CKEditor 4 default skin into your workspace.

For both options to work you must disable the custom CoreMedia rules for CKEditor 4 dialogs. This can be done by setting the SCSS variable $cm-include-richtextarea-dialog to false.

Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

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