DNN Blogs

Written for the Community, by the Community

Adding icons / buttons to a Toolbar in DNN CKEditor

Written By Timo Breumelhof (40F)

Due to the nature of CkEditor and how it’s configured, adding icons (plugins) to your CKEditor in DNN can be confusing. CKEditor is an open-source editor that is used by many CMS systems and website builders. It has to be configured in a certain way and the interface in DNN (when you click the “Custom Editor Options” link) exposes most of these settings. And as almost everything in CKEditor can be configured, the option screen looks quite complex especially the “Editor Config” tab. As is mostly the case, with flexibility comes complexity..

A button is a plugin in CKEditor

In CKEditor a toolbar icon is essentially just the access to a plugin, which defines the functionality.
Every plugin consists of a folder with the name of the plugin file inside the plugins folder.
This folder contains the files that are needed for the functionality of the plugin.
If plugin folder does not exist, the plugin will not show up in the DNN Editor.

The documentation for this principle can be found here: https://ckeditor.com/docs/ckeditor4/latest/guide/dev_plugins.html#manual-installation

In DNN the plugins folder is currently located here: “\Providers\HtmlEditorProviders\DNNConnect.CKE\js\ckeditor\4.15.1\plugins”

The same principle applies to adding a plugin in the DNN CKEditor.
As most editor settings are exposed in the “CKEditor Provider Settings” window, this is also where to add a plugin.
This is the window that opens when you click the [Custom Editor Options] link below the Editor.

Where CKEditor settings are stored.

There are three XML files in the root of the portal that are related to the settings.

Dnn.CKEditorSettings.xml = Editor settings
Dnn.CKToolbarButtons.xml = Available Icons for Toolbars
Dnn.CKToolbarSets.xml = Defined Toolbars

The Settings screen has 3 options: Modify Settings for "Site", "Page" and "Module".
When  you save settings for a Site, your settings are stored in the XML files mentioned above.
When you choose to save the configuration for “page” or “module”, the same xml is saved in the PageSettings or the ModuleSettings in the DNN Database, but for simplicity, I’ll stick to the “Site” option in my example.

Essentially you are editing these xml files when you change the Editor settings and those are passed to the editor when it’s loaded.

Example: add oembed plugin

As an example, we’ll add the oEmbed plugin, which allows easy embedding of for instance YouTube Videos

There are 3 things we need to do to add a plugin:

  1. Download the plugin
    Even if you see a plugin / button as an option for the “Custom Toolbars”, that does not mean the plugins Javascript comes with DNN.
    There are a few things you need to pay attention to when downloading a plugin:

    - The plugin must have the exact internal name (folder name) as the button in the settings screen.
    - You need to make sure you download the version for CKEditor 4
    - Check that the version works with the current version of CKEditor used in DNN.

    This is the link for the oembed plugin: https://ckeditor.com/cke4/addon/oembed
    Scroll to the bottom of the page and click [Download]
    After you downloaded the ZIP file, unzip in the Editor plugins folder
  2. Add the configuration to load the plugin
    CKEditor will only load extra plugins if they are added to the “ExtraPlugins” setting

    - Open a page with the HTML module on it and click Edit in the Module dropdown
    - Click the [ Custom Editor Options ] link below the editor
    - Open the Editor Config Tab.
    - Scroll down to the “ExtraPlugins” field.
    - Add the plugin name.

    By default this comma separated list only contains “dnnpages”, for our example, change this to “dnnpages,oembed”.
    (this will be stored in Dnn.CKEditorSettings.xml when you save)
  3. Add the icon to a toolbar.
    For this you open the “Custom Toolbars” tab.
    - Select a Toolbar
    - Click the Edit icon next to the drop down
    - The “Toolbar Groups” list will now show you the existing toolbars
    - The “Available Toolbar Buttons” shows icons you can add, although that does not mean that the actual plugin comes with DNN by default. This list is loaded from Dnn.CKToolbarButtons.xml
    - Drag an Icon from the “Available Toolbar Buttons” box to “Toolbar Groups”.
    - Click [Save]
    - The changed toolbar is now saved in Dnn.CKToolbarSets.xml
    - Click [Close]
    - Refresh the page.

The oEmbed plugin should be available now.

If you would want to add a plugin that is not in the “Available Toolbar Buttons” list, you obviously first need to download it and after that, you can either add the button by inserting it in the Dnn.CKToolbarButtons.xml file and use the function above.
Alternatively you can also manually edit the “Dnn.CKToolbarSets.xml” file.

I hope helps Admins that want to customize their Editor.
If you have issues following this description or think a part it not clear (enough), please leave a comment.

Total: 1 Comment(s)
Excellent blog post, Timo! Thank you for helping inform the community about cool things like this. :)
Tuesday, December 6, 2022 ·

Would you like to help us?

Awesome! Simply post in the forums using the link below and we'll get you started.

Get Involved