Latest revision as of 11:45, 18 May 2010

Writing plugins for CKFinder might be fun when you understand how to create them. Below you will find some basic guidelines on how to do it.

Creating a Plugin

You can create your own plugin in a four simple steps.

Step1: Create the Plugin Folder

Create a directory for your plugin inside of the plugins directory (by default CKFinder comes with three plugins built-in: dummy, fileeditor, imagreresize). Let us use myplugin as the plugin name and use the same name for our new folder.

Step2: Create the Plugin File

Inside your plugin folder (myplugin) create an empty file named plugin.js.

Step3: Add Plugin Definition

Plugins are registered with the CKFinder.addPlugin function.

CKFinder.addPlugin( 'myplugin', function( api ) {
	var toolId = api.addToolPanel( '<h3>My tool</h3><p>Sample content.</p>' );
	api.showTool( toolId );
} );

(Paste the code above to plugin.js and save the file.)

The plugin definition might be a function (where CKFinderAPI is passed as the first argument) or an object. See addPlugin function documentation for more details.

Step4: Enable the Plugin

To enable a plugin, use the extraPlugins configuration option in the config.js file:

CKFinder.customConfig = function( config )
{
	config.extraPlugins = 'myplugin';
};

Creating a Plugin — the Shorter Way

Sometimes (usually when developing a new plugin) it is more suitable to have the plugin definition in a single place, where CKFinder is created, instead of having it in a separate file (for example to avoid having to clear the browser cache).

Example

CKFinder.addPlugin( 'myplugin', function( api ) {
	api.addFileContextMenuOption( { label : 'My plugin', command : "myplugincommand" } , function( api, file )
	{
		api.openInputDialog( "Enter a number: ", "0", function( value ) {
			api.openMsgDialog( "You have entered: " + value );
		} );
	});
});	

var finder = new CKFinder();
finder.basePath = '/ckfinder/';
// Specify extraPlugins here, no need to change the config.js file.
finder.extraPlugins = 'myplugin';
finder.create();

See the "Public API" sample (_samples/public_api.html) for an example of such approach.

Localizing a Plugin

In the example above we hardcoded some strings (e.g. "Enter a number") that ideally should be moved to a separate file in order to allow translating them into other languages.

Specify Available Languages

Suppose we want to translate our plugin into English, French and Spanish. We will use the lang property to list all available languages.

CKFinder.addPlugin( 'pluginname', {
	// Available languages
	lang : [ 'en', 'es', 'fr' ],

	// Plugin definition
	appReady : function( api ) {
		// ...
		api.openMsgDialog( api.lang.pluginname.translationKey );
	}

});

Replace Hardcoded Strings with Variables

Replace each hardcoded string with a api.lang.[your plugin name].[translation key] variable.

Create Language Files

Add a lang subfolder inside the plugin folder and create three files: en.js, es.js, and fr.js.

In each file paste the following:

// setPluginLang( [Plugin name], [Language code], [Translations] );
CKFinder.setPluginLang( 'pluginname', 'en',
	{
		pluginname :
		{
			translationKey : 'Application is now ready to use',
			anotherKey : 'Another message'
			// ...
		}
	});

After the file is created, you can use the api.lang.pluginname.translationKey variable in the plugin definition instead of the "Application is now ready to use" string.

See the dummy plugin (plugins/dummy) distributed with CKFinder for an example.

Useful Resources

The following resources might prove useful when creating custom CKFinder plugins:

• Adding file context menu item
• Adding folder context menu item
• Getting selected file
• Getting selected folder
• Calling the server connector
• Creating a dialog window
• Adding a tool box (on the left side of the application)
• Full API documentation