Anna: Article contents added

2011-04-14T12:53:32Z

Article contents added

New page

{{#CUSTOMTITLE:Creating a CKEditor Plugin in 20 Lines of Code}}
__TOC__
The aim of this tutorial is to demonstrate how to create a most basic CKEditor plugin.

We are going to develop a '''timestamp plugin''' that inserts current date and time into the editing area of CKEditor. The timestamp will be added after a user clicks a dedicated toolbar button. Since the implementation makes use of the <code>insertHtml</code> function, this example can be easily adjusted to insert any other HTML element.

The plugin will be named <code>'''timestamp'''</code> and according to CKEditor [[FCKeditor 3.x/Design and Architecture/Coding Style|naming conventions]], this name will also be given to the plugin folder.

== Plugin Files ==
Firstly, we will need to create the <code>timestamp</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>timestamp</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>timestamp.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>timestamp</code>
**** <code>images</code>
***** <code>timestamp.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( 'timestamp',
{
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>'timestamp'</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 ===
It is customary for CKEditor plugins to define an editor command that performs an action associated with them. The command should be defined inside the <code>init</code> function in order to be called upon the initialization of a CKEditor instance.

In this case we are going to use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#addCommand addCommand]</code> function to define an <code>insertTimestamp</code> command that, as the name suggests, will insert the current date and time into a document created in CKEditor.

The <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.commandDefinition.html#exec exec]</code> method defines a function that will be fired when the <code>insertTimestamp</code> command is executed. Current date and time will be calculated using the JavaScript <code>[https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date Date]</code> object.

The most important part is to insert the HTML code into the document. To do this, we will use the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html#insertHtml insertHtml]</code> function from [http://docs.cksource.com/ckeditor_api/ CKEditor JavaScript API]. This function can be used to insert arbitrary HTML code into the document, so with a bit of tweaking you can customize the timestamp plugin code to add other HTML elements into the CKEditor editing area.
<source lang="javascript">
editor.addCommand( 'insertTimestamp',
{
exec : function( editor )
{
var timestamp = new Date();
editor.insertHtml( 'The current date and time is: <em>' + timestamp.toString() + '</em>' );
}
});
</source>

<note>Please note that there are other ways to insert code into CKEditor. Check the [http://docs.cksource.com/ckeditor_api/ CKEditor API Documentation] for more methods that let you add elements and do other useful things with CKEditor.</note>

=== Creating a Toolbar Button ===
The simplified timestamp plugin should work through a toolbar button. To this end, inside the <code>init</code> function we need to define a button that will be associated with the <code>insertTimestamp</code> command. The <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.ui.html#addButton CKEditor.ui.addButton]</code> function accepts a button name (<code>'Timestamp'</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( 'Timestamp',
{
label: 'Insert Timestamp',
command: 'insertTimestamp',
icon: this.path + 'images/timestamp.png'
} );
</source>

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

To register the plugin with CKEditor, we have to add its name 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 name 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 : 'timestamp',
toolbar :
[
[ 'Bold', 'Italic', '-', 'NumberedList', 'BulletedList', '-', 'Link', 'Unlink' ],
[ 'Timestamp' ]
]
});
//]]>
</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:timestamp_button_added.png|center|frame|Timestamp plugin button added to CKEditor toolbar]]

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

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

<div id="timestamp_full">
<source lang="javascript">
CKEDITOR.plugins.add( 'timestamp',
{
init: function( editor )
{
editor.addCommand( 'insertTimestamp',
{
exec : function( editor )
{
var timestamp = new Date();
editor.insertHtml( 'The current date and time is: <em>' + timestamp.toString() + '</em>' );
}
});
editor.ui.addButton( 'Timestamp',
{
label: 'Insert Timestamp',
command: 'insertTimestamp',
icon: this.path + 'images/timestamp.png'
} );
}
} );
</source>
</div>

== Working Example ==
The plugin code is now ready. When you click the '''Insert Timestamp''' toolbar button, current date and time will be inserted into the document. Note that the format of the timestamp may vary for different platforms and browsers. If you want to have more control over the display of the date and time, use the <code>[https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date Date]</code> object's properties and methods.

[[Image:timestamp_example.png|center|frame|Date and time added to the document in CKEditor]]

Congratulations! You have just created a valid CKEditor plugin in under 20 lines of code! Since the <code>insertHtml</code> function can be used to add arbitrary HTML code to the document, you can replace the timestamp logic with your own customized code in order to insert other types of content into your document.

CKEditor 3.x/Tutorials/Timestamp Plugin - Revision history

Anna: Article contents added