Revision as of 21:50, 16 May 2011

Creating CKFinder for Java Plugins

As mentioned in the Using CKFinder Plugins article, the functionality of CKFinder can be extended with code that is delegated to dedicated plugins. This architecture ensures that you do not need to modify CKFinder core to change the behavior of the application — using plugins is much more convenient.

This tutorial shows how to create a CKFinder plugin on the example of a FileSizePlugin which, as the name suggests, returns the size of the file.

In order to create a CKFinder plugin, you will need to follow the steps below:

Step 1: Create the plugin folder and file.
Step 2: Add the plugin definition.
Step 3: Make CKFinder aware of the new plugin.

Please note that for plugins that just add server-side functionality and do not contain any client-side scripts you can skip the first step.

Creating Plugin Folder and File

For a start, you need to create a directory for your plugin inside the /CKFinderJava-X.Y/ckfinder/plugins directory. Please note that by default CKFinder comes with three client-side plugins: dummy, fileeditor, and imagresize.

Remember that for CKFinder the name of the plugin folder is important and has to be the same as the name of the plugin, otherwise the application will not be able to recognize it.

Since our plugin is named filesizeplugin, the same name will be used for its folder. Inside the newly created filesizeplugin folder we are going to place the plugin.js file that will contain the plugin logic. Open the plugin.js file in an editor and add the following source code:

CKFinder.addPlugin( 'filesizeplugin', function( api ) {		// The name of the plugin.
	api.addFileContextMenuOption( { label : 'File Size', command : "FileSize" } , function( api, file )
	{
		api.connector.sendCommand( 'FileSize', { fileName : api.getSelectedFile().name }, function( xml )
		{
			if ( xml.checkError() )
				return; 
			var size = xml.selectSingleNode( 'Connector/FileSize/@size' );
			api.openMsgDialog( "", "The exact size of a file is: " + size.value + " bytes");
		} );
	});
});

Since the purpose of this tutorial is to show how to integrate plugins with CKFinder, we are not going to go into details of the JavaScript code. To sum it up, the plugin code above adds a new menu item to the user interface. This item, when selected, sends the FileSize command to the server, reads the XML response and displays the size of the queried file in a dialog window.

For more information on how to create JavaScript plugins refer to the Writing JavaScript Plugins article.

Making CKFinder Aware of the Plugin

Fast forward one step, this section describes how to make CKFinder aware that the plugin exists. Open the config.xml file and add a new plugin node to the plugins section.

<plugin>
	<name>filesizeplugin</name>
	<class>com.ckfinder.connector.plugins.FileSizePlugin</class>
	<params></params>
</plugin>

A plugin entry contains the following elements:

<name> – the name of the plugin that should be the same as the plugin folder name on the client side.
<class> – the plugin class extended from com.ckfinder.connector.configuration.Plugin.
<params> – additional plugin parameters. A parameter is added with a param node:
```
<param name="smallThumb" value="90x90" />
```

Java Plugin System

Events

CKFinder provides several events that can be used to extend the functionality of a CKFinder application. Assigning a class (also known as an event handler) to an event will cause that function to be called at an appropriate point in the main CKFinder code to perform whatever additional task(s) the developer considers useful at that point. Each event can have multiple event listeners assigned to it.

Available Events

Hook	Since	Description
AfterFileUpload	2.0	Executed after successful file upload.
BeforeExecuteCommand	2.0	Executed before a server side command is executed.
InitCommand	2.0	Executed straight before sending the result of the Init command.

@@ Line 1: / Line 1: @@
 __TOC__{{CKFinder 2.x Writing Plugins Introduction}}
-== Creating a Plugin ==
+= Creating CKFinder for Java Plugins =
+As mentioned in the [[CKFinder_2.x/Developers_Guide/Java/Plugins|Using CKFinder Plugins]] article, the functionality of CKFinder can be extended with code that is delegated to dedicated plugins. This architecture ensures that you do not need to modify CKFinder core to change the behavior of the application &mdash; using plugins is much more convenient.
-==== Step 1: Create plugin folder ====
+This tutorial shows how to create a CKFinder plugin on the example of a '''FileSizePlugin''' which, as the name suggests, returns the size of the file.
-==== Step 2: Add plugin definition ====
-==== Step 3: Enable plugin ====
+In order to create a CKFinder plugin, you will need to follow the steps below:
+* Step 1: Create the plugin folder and file.
+* Step 2: Add the plugin definition.
+* Step 3: Make CKFinder aware of the new plugin.
+Please note that for plugins that just add server-side functionality and do not contain any client-side scripts you can skip the first step.
+== Creating Plugin Folder and File ==
+For a start, you need to create a directory for your plugin inside the <code>/CKFinderJava-''X.Y''/ckfinder/plugins</code> directory. Please note that by default CKFinder comes with three client-side plugins: <code>dummy</code>, <code>fileeditor</code>, and <code>imagresize</code>.
+<note>Remember that for CKFinder the name of the plugin folder is important and has to be the same as the name of the plugin, otherwise the application will not be able to recognize it.</note>
+Since our plugin is named <code>filesizeplugin</code>, the same name will be used for its folder. Inside the newly created <code>filesizeplugin</code> folder we are going to place the <code>plugin.js</code> file that will contain the plugin logic.
+Open the <code>plugin.js</code> file in an editor and add the following source code:
+<source lang="javascript">
+CKFinder.addPlugin( 'filesizeplugin', function( api ) {		// The name of the plugin.
+	api.addFileContextMenuOption( { label : 'File Size', command : "FileSize" } , function( api, file )
+	{
+		api.connector.sendCommand( 'FileSize', { fileName : api.getSelectedFile().name }, function( xml )
+		{
+			if ( xml.checkError() )
+				return;
+			var size = xml.selectSingleNode( 'Connector/FileSize/@size' );
+			api.openMsgDialog( "", "The exact size of a file is: " + size.value + " bytes");
+		} );
+	});
+});
+</source>
+Since the purpose of this tutorial is to show how to integrate plugins with CKFinder, we are not going to go into details of the JavaScript code. To sum it up, the plugin code above adds a new menu item to the user interface. This item, when selected, sends the <code>FileSize</code> command to the server, reads the XML response and displays the size of the queried file in a dialog window.
+For more information on how to create JavaScript plugins refer to the [[CKFinder_2.x/Developers_Guide/Java/Plugins/Writing_JavaScript|Writing JavaScript Plugins]] article.
+== Making CKFinder Aware of the Plugin ==
+Fast forward one step, this section describes how to make CKFinder aware that the plugin exists. Open the <code>config.xml</code> file and add a new <code>plugin</code> node to the <code>plugins</code> section.
+<source lang="xml">
+<plugin>
+	<name>filesizeplugin</name>
+	<class>com.ckfinder.connector.plugins.FileSizePlugin</class>
+	<params></params>
+</plugin>
+</source>
+A plugin entry contains the following elements:
+* <code><name></code> &ndash; the name of the plugin that should be the same as the plugin folder name on the client side.
+* <code><class></code> &ndash; the plugin class extended from <code>com.ckfinder.connector.configuration.Plugin</code>.
+* <code><params></code> &ndash; additional plugin parameters. A parameter is added with a <code>param</code> node:
+*; <source lang="xml">
+<param name="smallThumb" value="90x90" />
+</source>
 == Java Plugin System ==

CKSource

Login / Create Account

Page Tools

Writing Java Plugins