The aim of this tutorial is to demonstrate how to create a basic CKEditor plugin.

We are going to develop an abbreviation plugin that lets the users insert abbreviations
into their documents. The abbreviations will be using the <abbr> HTML element and
will be added through a dialog window that is opened after clicking a dedicated
toolbar button.

The plugin will be named abbr, just like the name of the corresponding HTML
element that we are going to use in its implementation.

Firstly, we will need to create the abbr folder inside the plugins directory of
the CKEditor installation.

Remember that for CKEditor the name of the plugin folder 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 abbr folder we are going to place the plugin.js file that
will contain the plugin logic. Apart from that, since we will also need a toolbar
icon for our plugin, we are going to add an icons folder and subsequently
place the abbr.png file inside. Finally, we will create the dialogs folder with theabbr.js file, which will store the definition for the dialog we will use in our plugin.

To sum up, we will need the following file structure for our plugin to work:

All CKEditor plugins are created by using the CKEDITOR.plugins.add function.
This function should contain the plugin name — 'abbr' — and the plugin logic
placed inside the CKEDITOR.pluginDefinition.init function that is
called upon the initialization of the editor instance.

Additionally, as we are going to define a toolbar button, the icons property is set, including the name of the icon file (important: matching the button name, in lowercase).

We want our plugin to have a dialog window, so we need to define an editor
command that opens a new dialog window. To do this, we will need to use
the editor.addCommand function to register theabbr command.

Please note that you can influence the position of the button in the toolbar group by providing an optional index, for example:

// This could position the button at the beginning of the "insert" group.
toolbar: 'insert,0'
// This could position the button at the end of the "insert" group.
toolbar: 'insert,100'

Note: The exact position depends on the indexes defined by other buttons available in your toolbar, so it may take some experimenting with index values to create a perfect button sequence within a group.

Clicking the button should open the abbrDialog dialog window. One interesting aspect of it is that it is possible to define dialogs in separate files which are loaded on demand. In our case, we will tell the editor to load the dialog from the dialogs/abbr.js file when the button is clicked. To do so, we need to add the following line to the init function:

CKEDITOR.dialog.add( 'abbrDialog', this.path + 'dialogs/abbr.js' );

In the code above we registered the abbrDialog dialog name, telling the editor to load the dialog definition from the dialog/abbr.js file out of the plugin installation folder (this.path).

The Basic Settings tab will contain two mandatory text fields (type: 'text')
with the abbreviation and its explanation. Since both fields are obligatory, it is
useful to add a simple validation mechanism in order to ensure that the user
fills them.

The Advanced Settings tab will contain a single optional text field that allows
the user to assign an ID to the abbreviation element.

The code snippet presented below shows a full definition of the contents of both
plugin tabs.

The presentation layer of the plugin is now ready, so we can define the plugin
behavior to actually make it work.

The onOk method is invoked once the user
accepts the changes introduced in the
dialog window by clicking the OK button or pressing the Enter key on the
keyboard. Since the plugin adds a new <abbr> element to the DOM tree, we
can use the createElement function to
create a new DOM element.

With the new DOM element created, we can now retrieve the values of thetitle and (optional) id fields with thegetValueOf function and pass them to
appropriate <abbr> element attributes by using thesetAttribute function.

Finally, we will pass the text entered into the abbr text field as the contents
of the <abbr> element by using thesetText function.

With the contents of the <abbr> element ready, we can insert it into the
document at the location of the cursor by using theinsertElement function.

Add the following onOk function code to your dialog window definition, below
the code that creates the content of the dialog.

Please note that another way to insert HTML code into CKEditor is by using the insertHtml function that adds HTML code at the location of the cursor in the document: editor.insertHtml( ‘<h2>This is a sample header</h2><p>This is a sample paragraph.</p>’ );

The plugin code is now ready. When you click the Insert Abbreviation toolbar
button, the Abbreviation Properties dialog window will open. Fill in the
obligatory Abbreviation and Explanation fields and click the OK button.

The newly added abbreviation will be inserted into the document and will be
displayed using the default styling of your browser. In Firefox, for example,
the abbreviation will be underlined using a dotted line and the explanation
will be displayed in a tooltip.

The Abbreviation plugin is now able to add a new <abbr> element to the document,
but does not make it possible to edit an already existing element. For this
feature along with the context menu support check thesecond part of the tutorial.