Contents
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: