CKEditor 3.x/Tutorials/Abbr Plugin Part 1 - Revision history

Anna: <abbr> escaped

2012-05-09T12:39:00Z

<abbr> escaped

Fredck: /* Creating an Editor Command */

2011-08-10T11:01:56Z

‎Creating an Editor Command

Saare: Fixing a tutorial link

2011-04-14T14:16:22Z

Fixing a tutorial link

Anna: Article contents added

2011-04-14T13:06:02Z

Article contents added

New page

{{#CUSTOMTITLE:Creating a Simple CKEditor Plugin}}
__TOC__
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 user insert abbreviations into their documents. The abbreviations will be using the <code>abbr</code> HTML element and will be added through a dialog window that is opened after clicking a dedicated toolbar button.

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

== Plugin Files ==
Firstly, we will need to create the <code>abbr</code> folder inside the <code>plugins</code> directory of the CKEditor installation.

<note>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.</note>

Inside the newly created <code>abbr</code> folder we are going to place the <code>plugin.js</code> 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 <code>images</code> folder and subsequently place the <code>icon.png</code> file inside.

To sum up, we will need the following file structure for our plugin to work:
* <code>''ckeditor root''</code>
** <code>plugins</code>
*** <code>abbr</code>
**** <code>images</code>
***** <code>icon.png</code>
**** <code>plugin.js</code>

== Plugin Source Code ==
With the following structure ready, it is time to open the <code>plugin.js</code> file in a text editor and to start creating the source code of the plugin.

<source lang="javascript">
CKEDITOR.plugins.add( 'abbr',
{
init: function( editor )
{
// Plugin logic goes here...
}
} );
</source>

All CKEditor plugins are created by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.resourceManager.html#add CKEDITOR.plugins.add]</code> function. This function should contain the plugin name (<code>'abbr'</code>) and the plugin logic placed inside the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.pluginDefinition.html#init init]</code> function that is called upon the initialization of the editor instance.

=== Creating an Editor Command ===
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 <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#addCommand addCommand]</code> function opening the <code>abbrDialog</code> window that we are going to define in a moment by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialogCommand.html CKEDITOR.dialogCommand]</code> function.

<source lang="javascript">
editor.addCommand( 'abbrDialog',new CKEDITOR.dialogCommand( 'abbrDialog' ) );
</source>

=== Creating a Toolbar Button ===
The plugin dialog window is to be opened by using a toolbar button. To this end, we need to define a button that will be associated with the dialog window. The <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.ui.html#addButton CKEditor.ui.addButton]</code> function accepts a button name (<code>'Abbr'</code>) along with the definition of the tooltip text (<code>label</code>) and the button icon (<code>icon</code>). Note that <code>this.path</code> is the directory where the <code>plugin.js</code> file resides.

These parameters are responsible for the button presentation. To make the button actually work, we need to connect it to the plugin command name defined above by using the <code>command</code> parameter.

<source lang="javascript">
editor.ui.addButton( 'Abbr',
{
label: 'Insert Abbreviation',
command: 'abbrDialog',
icon: this.path + 'images/icon.png'
} );
</source>

=== CKEditor Initialization ===
It is now time to initialize a CKEditor instance that will use the Abbreviation plugin along with its toolbar button.

To register the plugin with CKEditor, we have to add it to the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.extraPlugins extraPlugins]</code> list. We also need to enhance the toolbar definition and add the plugin button by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.toolbar toolbar]</code> parameter.

Open the page that will contain CKEditor in a text editor and insert a CKEditor instance using the following toolbar and plugin configuration.

<source lang="javascript">
<script type="text/javascript">
//<![CDATA[
// Replace the <textarea id="editor1"> with a CKEditor
// instance, using default configuration.
CKEDITOR.replace( 'editor1',
{
extraPlugins : 'abbr',
toolbar :
[
['Bold', 'Italic', '-', 'NumberedList', 'BulletedList', '-', 'Link', 'Unlink'],
['About','-','Abbr']
]
});
//]]>
</script>
</source>

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.

[[Image:abbr_button_added.png|center|frame|Abbreviation plugin button added to CKEditor toolbar]]

=== Plugin Dialog Window ===
Clicking the button should open the <code>abbrDialog</code> dialog window. First, however, we need to return to the Abbreviation plugin source file and define the dialog window by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.html#.add CKEDITOR.dialog.add]</code> function. To see all dialog window definition elements, refer to the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html CKEditor JavaScript API].

In our case we will give the dialog window a name (<code>'abbrDialog'</code>) and use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#title title]</code>, <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#minWidth minWidth]</code>, and <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#minHeight minHeight]</code> parameters to define its title and minimum dimensions, respectively.

<note>The name selected for the dialog window is the name that appears in the <code>addCommand</code> function above.
</note>

==== Dialog Window Tabs ====
The dialog window should also contain some [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#contents contents], so we will begin with [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.contentDefinition.html adding] two tabs along with their labels. Note that by default CKEditor also adds the standard '''OK''' and '''Cancel''' buttons.

In order to create the Abbreviation plugin dialog window along with two tabs, add the following code in the <code>plugin.js</code> file below the plugin toolbar button definition.
<source lang="javascript">
CKEDITOR.dialog.add( 'abbrDialog', function ( editor )
{
return {
title : 'Abbreviation Properties',
minWidth : 400,
minHeight : 200,

contents :
[
{
id : 'tab1',
label : 'Basic Settings',
elements :
[
// UI elements of the first tab will be defined here
]
},
{
id : 'tab2',
label : 'Advanced Settings',
elements :
[
// UI elements of the second tab will be defined here
]
}
]
};
} );
</source>
The result of this change can be seen immediately. Click the '''Insert Abbreviation''' toolbar button in order to open the newly created '''Abbreviation Properties''' dialog window containing two (empty) tabs.

[[Image:abbr_empty_tabs.png|center|frame|A plugin dialog window with two tabs added]]

==== Dialog Window Tabs Elements ====
User interface elements that can be added to a dialog window tab are defined in the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.contentDefinition.html#elements elements]</code> parameter, which is an array of <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.uiElementDefinition.html CKEDITOR.dialog.uiElementDefinition]</code> objects.

The '''Basic Settings''' tab will contain two mandatory text fields (<code>type : 'text'</code>) 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 <code>id</code> to the abbreviation element.

The code snippet presented below shows a full definition of the contents of both plugin tabs.
<source lang="javascript">
contents :
[
{
id : 'tab1',
label : 'Basic Settings',
elements :
[
{
type : 'text',
id : 'abbr',
label : 'Abbreviation',
validate : CKEDITOR.dialog.validate.notEmpty( "Abbreviation field cannot be empty" )
},
{
type : 'text',
id : 'title',
label : 'Explanation',
validate : CKEDITOR.dialog.validate.notEmpty( "Explanation field cannot be empty" )
}
]
},
{
id : 'tab2',
label : 'Advanced Settings',
elements :
[
{
type : 'text',
id : 'id',
label : 'Id'
}
]
}
]
</source>

When you reload the editor instance and open the '''Abbreviation Properties''' dialog window, the '''Basic Settings''' tab will now contain two mandatory text fields.

[[Image:abbr_basic_settings_tab.png|center|frame|Basic Settings tab of the Abbreviation plugin]]

The '''Advanced Settings''' tab only contains a single <code>id</code> text field that can be left empty.

[[Image:abbr_advanced_settings_tab.png|center|frame|Advanced Settings tab of the Abbreviation plugin]]

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

The <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#onOk onOk]</code> 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 <code>abbr</code> element to the DOM tree, we can use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.document.html#createElement createElement]</code> function to create a new DOM element.

With the new DOM element created, we can now retrieve the values of the <code>title</code> and (optional) <code>id</code> fields with the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.html#getValueOf getValueOf]</code> function and pass them to appropriate <code>abbr</code> element attributes by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.element.html#setAttribute setAttribute]</code> function.

Finally, we will pass the text entered in the <code>abbr</code> text field as the contents of the <code>abbr</code> element by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.element.html#setText setText]</code> function.

With the contents of the <code>abbr</code> element ready, we can insert it into the document at the location of the cursor by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#insertElement insertElement]</code> function.

Add the following <code>onOk</code> function code to your dialog window definition, below the code that creates the contents of the dialog.

<source lang="javascript">
onOk : function()
{
var dialog = this;
var abbr = editor.document.createElement( 'abbr' );

abbr.setAttribute( 'title', dialog.getValueOf( 'tab1', 'title' ) );
abbr.setText( dialog.getValueOf( 'tab1', 'abbr' ) );

var id = dialog.getValueOf( 'tab2', 'id' );
if ( id )
abbr.setAttribute( 'id', id );

editor.insertElement( abbr );
}
</source>

<note>Please note that another way to insert HTML code into CKEditor is using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#insertHtml insertHtml]</code> function that adds HTML code at the location of the cursor in the document.

<source lang="javascript">
editor.insertHtml( '<h2>This is a sample header</h2><p>This is a sample paragraph.</p>' );
</source>
</note>

== Full Source Code ==
To see the full contents of the <code>plugin.js</code> file, <hide target="abbr_full">click here</hide>.

<note>You can also [[Media:abbr.zip|download the whole plugin folder]] inluding the icon and the fully commented source code.
</note>

<div id="abbr_full">
<source lang="javascript">
CKEDITOR.plugins.add( 'abbr',
{
init: function( editor )
{
editor.addCommand( 'abbrDialog',new CKEDITOR.dialogCommand( 'abbrDialog' ) );
editor.ui.addButton( 'Abbr',
{
label: 'Insert Abbreviation',
command: 'abbrDialog',
icon: this.path + 'images/icon.png'
} );
CKEDITOR.dialog.add( 'abbrDialog', function( editor )
{
return {
title : 'Abbreviation Properties',
minWidth : 400,
minHeight : 200,
contents :
[
{
id : 'tab1',
label : 'Basic Settings',
elements :
[
{
type : 'text',
id : 'abbr',
label : 'Abbreviation',
validate : CKEDITOR.dialog.validate.notEmpty( "Abbreviation field cannot be empty" )
},
{
type : 'text',
id : 'title',
label : 'Explanation',
validate : CKEDITOR.dialog.validate.notEmpty( "Explanation field cannot be empty" )
}
]
},
{
id : 'tab2',
label : 'Advanced Settings',
elements :
[
{
type : 'text',
id : 'id',
label : 'Id'
}
]
}
],
onOk : function()
{
var dialog = this;

var abbr = editor.document.createElement( 'abbr' );
abbr.setAttribute( 'title', dialog.getValueOf( 'tab1', 'title' ) );
abbr.setText( dialog.getValueOf( 'tab1', 'abbr' ) );
var id = dialog.getValueOf( 'tab2', 'id' );
if ( id )
abbr.setAttribute( 'id', id );
editor.insertElement( abbr );
}
};
} );
}
} );
</source>
</div>

== Working Example ==
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.

[[Image:abbr_example1.png|center|frame|Abbreviation added in the dialog window]]

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.

[[Image:abbr_example2.png|center|frame|Abbreviation added in the dialog window]]

== Further Enhancements ==
The Abbreviation plugin is now able to add a new <code>abbr</code> 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 the [[CKEditor 3.x/Developers Guide/Customization/Plugins/Abbr Plugin Part 2|second part of the tutorial]].

← Older revision		Revision as of 14:16, 14 April 2011
Line 321:		Line 321:

	== Further Enhancements ==		== Further Enhancements ==
−	The Abbreviation plugin is now able to add a new <code>abbr</code> 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 the [[CKEditor 3.x/~~Developers Guide~~/~~Customization/Plugins/Abbr Plugin Part 2~~\|second part of the tutorial]].	+	The Abbreviation plugin is now able to add a new <code>abbr</code> 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 the [[CKEditor 3.x/Tutorials/Abbr_Plugin_Part_2\|second part of the tutorial]].

@@ Line 3: / Line 3: @@
 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 user insert abbreviations into their documents. The abbreviations will be using the <code>abbr</code> HTML element and will be added through a dialog window that is opened after clicking a dedicated toolbar button.
+We are going to develop an '''abbreviation plugin''' that lets the user insert abbreviations into their documents. The abbreviations will be using the <code>&lt;abbr&gt;</code> HTML element and will be added through a dialog window that is opened after clicking a dedicated toolbar button.
 The plugin will be named <code>'''abbr'''</code>, just like the name of the corresponding HTML element that we are going to use in its implementation.
@@ Line 195: / Line 195: @@
 The presentation layer of the plugin is now ready, so we can define the plugin behavior to actually make it work.
-The <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#onOk onOk]</code> 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 <code>abbr</code> element to the DOM tree, we can use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.document.html#createElement  createElement]</code> function to create a new DOM element.
+The <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.dialogDefinition.html#onOk onOk]</code> 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 <code>&lt;abbr&gt;</code> element to the DOM tree, we can use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.document.html#createElement  createElement]</code> function to create a new DOM element.
-With the new DOM element created, we can now retrieve the values of the <code>title</code> and (optional) <code>id</code> fields with the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.html#getValueOf getValueOf]</code> function and pass them to appropriate <code>abbr</code> element attributes by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.element.html#setAttribute  setAttribute]</code> function.
+With the new DOM element created, we can now retrieve the values of the <code>title</code> and (optional) <code>id</code> fields with the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialog.html#getValueOf getValueOf]</code> function and pass them to appropriate <code>&lt;abbr&gt;</code> element attributes by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.element.html#setAttribute  setAttribute]</code> function.
-Finally, we will pass the text entered in the <code>abbr</code> text field as the contents of the <code>abbr</code> element by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.element.html#setText setText]</code> function.
+Finally, we will pass the text entered in the <code>abbr</code> text field as the contents of the <code>&lt;abbr&gt;</code> element by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dom.element.html#setText setText]</code> function.
-With the contents of the <code>abbr</code> element ready, we can insert it into the document at the location of the cursor by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#insertElement insertElement]</code> function.
+With the contents of the <code>&lt;abbr&gt;</code> element ready, we can insert it into the document at the location of the cursor by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#insertElement insertElement]</code> function.
 Add the following <code>onOk</code> function code to your dialog window definition, below the code that creates the contents of the dialog.
@@ Line 321: / Line 321: @@
 == Further Enhancements ==
-The Abbreviation plugin is now able to add a new <code>abbr</code> 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 the [[CKEditor 3.x/Tutorials/Abbr_Plugin_Part_2|second part of the tutorial]].
+The Abbreviation plugin is now able to add a new <code>&lt;abbr&gt;</code> 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 the [[CKEditor 3.x/Tutorials/Abbr_Plugin_Part_2|second part of the tutorial]].

@@ Line 39: / Line 39: @@
 === Creating an Editor Command ===
-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 <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#addCommand  addCommand]</code> function opening the <code>abbrDialog</code> window that we are going to define in a moment by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialogCommand.html CKEDITOR.dialogCommand]</code> function.
+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 <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#addCommand  addCommand]</code> function to register the <code>abbrDialog</code> command. That command opens the <code>abbrDialog</code> dialog that we are going to define in a moment by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.dialogCommand.html CKEDITOR.dialogCommand]</code> class.
 <source lang="javascript">
-editor.addCommand( 'abbrDialog',new CKEDITOR.dialogCommand( 'abbrDialog' ) );
+editor.addCommand( 'abbrDialog', new CKEDITOR.dialogCommand( 'abbrDialog' ) );
 </source>