close

Filter

loading table of contents...

Studio Developer Manual / Version 2204

Table Of Contents

9.6.5.6 Customizing CKEditor

The CKEditor provides richtext editing capabilities in a browser independent way. It has a plugin-driven architecture. Plugins are JavaScript files that are loaded at the end of the CKEditor loading process, before the initialization and activation of CKEditor 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. The CKEditor 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 9.38. 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 9.39. Adding the refrerence 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 9.40. Customizing the CKEditor


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 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 API documentation is available at http://docs.ckeditor.com/#!/api.

The custom plugin can now be registered by the CKEditor. 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. This is done by using the RemoveCKEditorPluginsPlugin in your RichTextArea. To remove the CKEditor plugin about, for example, add the following to your declaration:

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

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

To change other configuration options of CKEditor, you can use the CustomizeCKEditorPlugin with your RichTextArea. A list of CKEditor configuration options can be found here: CKEditor.config For example, to instruct the CKEditor 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 9.41. Customizing the CKEditor configuration


Items or Buttons which execute custom CKEditor commands have to be added to the richtext toolbar using the AddItemsPlugin as described in Section 9.6.5.5, “Customizing Richtext Toolbar”. This cannot be done in the CKEditor directly.

Styling of CKEditor Dialogs

As some original CKEditor 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 dialogs there are two possible ways to do so:

  1. Using the CKEditor configuration option skin (see Example 9.41, “Customizing the CKEditor configuration”) and provide your own CKEditor skin that overrides the dialog.css (see http://docs.ckeditor.com/#!/guide/skin_sdk_intro).

    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 9.42. 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 9.6.5.6, “Customizing CKEditor” 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 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 default skin into your workspace.

For both options to work you must disable the custom CoreMedia rules for CKEditor 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.