Template:Writing JavaScript Plugins - Revision history

Anna: Template contents proof-read and formatted

2011-04-01T10:37:52Z

Template contents proof-read and formatted

Wiktor: Created page with '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 you…'

2010-05-18T10:45:12Z

Created page with '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 you…'

New page

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 [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinder.html#.addPlugin CKFinder.addPlugin] function.

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

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

The plugin definition might be a function (where [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinderAPI.html CKFinderAPI] is passed as the first argument) or an object. See [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinder.html#.addPlugin addPlugin documentation] for more details.

==== Step4: Enable plugin ====

To enable a plugin, use the [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinder.config.html#.extraPlugins extraPlugins] configuration option in '''config.js''':

<source>
CKFinder.customConfig = function( config )
{
config.extraPlugins = 'myplugin';
};
</source>

== 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 ====
<source>
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();
</source>

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 <code>lang</code> property.

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

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

});
</source>

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

<source>
// setPluginLang( [Plugin name], [Language code], [Translations] );
CKFinder.setPluginLang( 'pluginname', 'en',
{
pluginname :
{
translationKey : 'Application is now ready to use',
anotherKey : 'Another message'
// ...
}
});
</source>
After creating such file, we can use <code>api.lang.pluginname.translationKey</code> 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 ==

* [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinderAPI.html#addFileContextMenuOption Adding file context menu item]
* [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinderAPI.html#addFolderContextMenuOption Adding folder context menu item]
* [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinderAPI.html#getSelectedFile Getting selected file]
* [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinderAPI.html#getSelectedFolder Getting selected folder]
* [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinder.dataTypes.Connector.html#sendCommand Calling the server connector]
* [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinder.dialog.html#.add Creating a dialog]
* [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinderAPI.html#addToolPanel Adding tool box] (on the left side of the application)
* [http://docs.cksource.com/ckfinder_2.x_api/ Full API documentation]

{{#CUSTOMTITLE:Writing JavaScript Plugins}}

@@ Line 1: / Line 1: @@
-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.
+__TOC__
+{{#CUSTOMTITLE:Writing JavaScript Plugins}}
-== Creating a plugin ==
+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.
 You can create your own plugin in a four simple steps.
-==== Step1: Create plugin folder ====
+==== Step1: Create the Plugin Folder ====
+Create a directory for your plugin inside of the <code>plugins</code> directory (by default CKFinder comes with three plugins built-in: <code>dummy</code>, <code>fileeditor</code>, <code>imagreresize</code>). Let us use <code>myplugin</code> as the plugin name and use the same name for our new folder.
-Inside of your plugin's folder ("myplugin") create an empty file named '''plugin.js'''.
+==== Step2: Create the Plugin File ====
-==== Step3: Add plugin definition ====
+==== Step3: Add Plugin Definition ====
-Plugins are registered with [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinder.html#.addPlugin CKFinder.addPlugin] function.
+<source lang="javascript">
 CKFinder.addPlugin( 'myplugin', function( api ) {
 	var toolId = api.addToolPanel( '<h3>My tool</h3><p>Sample content.</p>' );
@@ Line 24: / Line 22: @@
 </source>
-(Paste the code above to plugin.js and save the file.)
+(Paste the code above to <code>plugin.js</code> and save the file.)
-The plugin definition might be a function (where [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinderAPI.html CKFinderAPI] is passed as the first argument) or an object. See [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinder.html#.addPlugin addPlugin documentation] for more details.
+The plugin definition might be a function (where <code>[http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinderAPI.html CKFinderAPI]</code> is passed as the first argument) or an object. See [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinder.html#.addPlugin <code>addPlugin</code> function documentation] for more details.
-==== Step4: Enable plugin ====
+==== Step4: Enable the Plugin ====
-To enable a plugin, use the [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinder.config.html#.extraPlugins extraPlugins] configuration option in '''config.js''':
+<source lang="javascript">
 CKFinder.customConfig = function( config )
+{
@@ Line 39: / Line 36: @@
 </source>
-== Creating a plugin - the shorter way ==
+== Creating a Plugin &mdash; 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).
+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 ====
-<source>
+<source lang="javascript">
 CKFinder.addPlugin( 'myplugin', function( api ) {
 	api.addFileContextMenuOption( { label : 'My plugin', command : "myplugincommand" } , function( api, file )
@@ Line 56: / Line 53: @@
 var finder = new CKFinder();
 finder.basePath = '/ckfinder/';
-// Specify extraPlugins here, no need to change config.js
+// Specify extraPlugins here, no need to change the config.js file.
 finder.extraPlugins = 'myplugin';
 finder.create();
 </source>
-See the public API sample (_samples/public_api.html) for an example of such approach.
+See the "Public API" sample (<code>_samples/public_api.html</code>) for an example of such approach.
-== Localizing a plugin ==
+== 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 ====
-==== Specify available languages ====
+<source lang="javascript">
 CKFinder.addPlugin( 'pluginname', {
 	// Available languages
@@ Line 85: / Line 80: @@
 </source>
-==== Replace hardcoded strings with variables ====
+==== Replace Hardcoded Strings with Variables ====
-Replace each hardcoded string with api.lang.[your plugin name].[translation key]
+==== Create Language Files ====
 In each file paste the following:
-<source>
+<source lang="javascript">
 // setPluginLang( [Plugin name], [Language code], [Translations] );
 CKFinder.setPluginLang( 'pluginname', 'en',
@@ Line 106: / Line 100: @@
 	});
 </source>
-See the dummy plugin (plugins/dummy) distributed with CKFinder for an example.
+After the file is created, you can use the <code>api.lang.pluginname.translationKey</code> variable in the plugin definition instead of the "Application is now ready to use" string.
-== Useful resources ==
+See the <code>dummy</code> plugin (<code>plugins/dummy</code>) distributed with CKFinder for an example.
 * [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinderAPI.html#addFileContextMenuOption Adding file context menu item]
 * [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinderAPI.html#addFolderContextMenuOption Adding folder context menu item]
@@ Line 117: / Line 112: @@
 * [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinderAPI.html#getSelectedFolder Getting selected folder]
 * [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinder.dataTypes.Connector.html#sendCommand Calling the server connector]
-* [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinder.dialog.html#.add Creating a dialog]
+* [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinder.dialog.html#.add Creating a dialog window]
-* [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinderAPI.html#addToolPanel Adding tool box] (on the left side of the application)
+* [http://docs.cksource.com/ckfinder_2.x_api/symbols/CKFinderAPI.html#addToolPanel Adding a tool box] (on the left side of the application)
 * [http://docs.cksource.com/ckfinder_2.x_api/ Full API documentation]