Revision as of 19:36, 17 May 2010

Writing plugins for CKFinder might be fun when you understand how to create them. Below you'll find a short instruction how to do it.

Creating a plugin

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

Step1: Create plugin folder

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

Step2: Create plugin file

Inside of your plugin's folder ("myplugin") create an empty file named plugin.js.

Step3: Add plugin definition

Plugins are registered with 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 documentation for more details.

Step4: Enable plugin

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

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 we create CKFinder, instead of having it in a separate file (for example to avoid having to clear browser's 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 config.js
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 have hardcoded some strings (e.g. "Enter a number") that ideally should be moved to a separate file to allow translating it into other languages.

Specify available languages

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

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 api.lang.[your plugin name].[translation key]

Create a file for each language

Create a "lang" subfolder inside of a plugins folder and create there 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 creating such file, we can use api.lang.pluginname.translationKey in the plugin definition instead of "Application is now ready to use".

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

Useful resources

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