The aim of this tutorial is to demonstrate how to create a basic CKEditor widget plugin.
Prerequisites
Widgets are an innovative feature that is available since CKEditor 4.3. In order to proceed with this tutorial and create your own widget you need the following:
- CKEditor 4.3 and above.
- The Widget plugin along with its dependencies.
Introduction
We are going to develop a basic template widget that lets the user insert a simple box with a title and comment fields into the document. The widget will create a predefined content structure that will be added to the document when the user clicks a dedicated toolbar button.
Please note that technically widgets are defined in CKEditor plugins so all the rules of creating plugins as well as the Plugin API apply to them. Additionally, widgets also expose a dedicated Widget API that we are going to use (and explain) in this tutorial.
The widget plugin will be named simplebox.
Widget Plugin Files
Firstly, we will need to create the simplebox directory inside the plugins directory of the CKEditor installation.
Remember that for CKEditor the name of the plugin directory is important and has to be the same as the name of the plugin, otherwise the editor will not be able to recognize it.
Inside the newly created simplebox directory we are going to place the plugin.js file that will contain the widget logic. Apart from that, since we will also need a toolbar icon for our widget, we are going to add an icons directory and subsequently place the simplebox.png file inside.
To sum up, we will need the following file structure for our plugin to work:
ckeditor root/plugins/simplebox/icons/simplebox.png
plugin.js
Widget Source Code
With the following structure ready, it is time to open the plugin.js file in a text editor and to start creating the source code of our sample widget.
CKEDITOR.plugins.add( 'simplebox', {
// Simple Box widget code.
} );All CKEditor plugins are created by using the CKEDITOR.plugins#add function. This function should contain the plugin name (again, the same as the directory name, so simplebox in our case) and the plugin logic placed inside the init function that is called upon the initialization of the editor instance.
The simplebox plugin is going to define the simplebox widget. To do this, the plugin needs to reference the generic Widget plugin that provides the Widget API. This is done in the requires property.
Additionally, as we are going to define a toolbar button, the icons property needs to be set and include the name of the icon file.
Please note the special naming convention for widget toolbar buttons. The Widget API will only be able to automatically add the button to the toolbar if the name of the icon is the same as the widget. In this case this will be simplebox. Do remember that the icons property accepts a PNG icon file name without an extension.
CKEDITOR.plugins.add( 'simplebox', {
requires: 'widget',
icons: 'simplebox',
init: function( editor ) {
// Plugin logic goes here...
}
} );Widget Registration
We now need to use the Widget API to register the widget with the editor instance. This is done by using the editor.widgets.add method inside the plugin initialization logic.
init: function( editor ) {
editor.widgets.add( 'simplebox', {
// Widget code.
} );
}The editor.widgets.add method accepts a number of parameters (wrapped as an instance of the CKEDITOR.plugins.widget.definition class) that let you define the widget properties, including the toolbar button, content required by the widget and allowed in the widget elements, widget building blocks, and its template. Last but not least, we need to define the elements that will be converted into widgets in the editor.
Widget Toolbar Button
A toolbar button can be added by defining the button property. This property accepts the label for the button and if defined, automatically adds the button (with the icon defined in the icons property of the CKEDITOR.plugins.add method, identical to the widget name, and the label defined here) to the editor toolbar.
editor.widgets.add( 'simplebox', {
button: 'Create a simple box'
} );Please note that normally you would place the label in the editor.lang.simplebox.* property to make it possible to localize it. In this case, however, we will simplify the widget code and add the label text literally as a string.
CKEditor Initialization
It is now time to initialize a CKEditor instance that will use the Simple Box widget along with its toolbar button.
To register the widget plugin with CKEditor, we have to add it to the config.extraPlugins list. In this particular case, to make screenshots more clear, we also enhanced the toolbar definition and removed some unnecessary plugins that we will not need in this sample, but you can try it out on any installation package of CKEditor 4.3 and above that contains the Widget plugin.
Open the page that will contain CKEditor in a text editor and insert a CKEditor instance using the following configuration.
After you load the page containing the above CKEditor instance, you should be able to see the new plugin toolbar button along with its tooltip.
Creating Widget Elements
We now need to create the widget structure. This can be achieved by using the template property of the widget definition.
Each widget consists of one or more HTML elements defined by the widget author. Once set, this structure becomes immutable, which means that it cannot be altered by the user. This ensures that the widget structure remains intact and the user will not be able to accidentally alter it or delete one of its parts.
Let us define a simple widget template that will consist of two fields: a title field (using a
element) and a content field (using a
element).
editor.widgets.add( 'simplebox', {
// Code defined before...
template:
'' +
'Title' +
'Content...' +
''
} );sdfds
