Creating CKFinder 3 Plugins

Contents

The aim of this article is to explain how to create a most basic CKFinder plugin.

Creating a Plugin in 5 Minutes

Learn by coding! You are going to develop a custom plugin that displays a dialog window with a message when CKFinder starts.

Save the following code as plugins/MyPlugin/MyPlugin.js:

 CKFinder.define( function () {

     var MyPlugin = {
         init: function ( finder ) {
             finder.on( 'app:ready', function ( evt ) {
                 finder.request( 'dialog:info', {
                     msg: 'Welcome to CKFinder!'
                 } );
             } );
         }
     };

     return MyPlugin;
 } );

Enable the plugin. Open config.js and set config.plugins:
```
 CKFinder.define( {
     plugins: 'MyPlugin'
 } );
```
Clear the browser cache and open a sample with CKFinder. A dialog message should appear immediately after the application starts.

A dialog window shown by CKFinder

Plugin Code Explained

Refer to the following notes for some code explanations.

Plugin Requirements

Each plugin must be defined using CKFinder.define. The CKFinder.define method allows for loading requirements if a plugin needs them. See the FolderInfo plugin code for an example of loading dependencies such as underscore, doT, backbone or marionette.

Note: jQuery must also be defined as a dependency if it is used — see the CustomButton plugin code for an example.

Plugin Definition

The CKFinder.Plugin definition needs to be provided in each plugin. The plugin definition shall include the init method that will be executed when CKFinder starts.

Optionally, a plugin may also add its own CSS styles using the addCss method — see the CustomButton plugin code for an example.

The init Method

Inside the init method you have access to the CKFinder instance (CKFinder.Application).

This is the main API entry point allowing you to interact with the application. In this simple plugin two important things are done:

Listening for the app:ready event using finder.on.
Requesting CKFinder to open a simple dialog window (dialog:info) and display the message provided in the msg parameter with finder.request.

All available events and requests are documented in the CKFinder.Application documentation.

Requests

Requests are used in CKFinder to command the application to perform some action. All requests are documented in the CKFinder.Application documentation.

Among many features, requests allow for:

Sending commands to the server connector.
Opening custom dialog windows.
Working on files and folders, including getting information about selected files or an active folder.
Creating custom pages with a custom toolbar.
Creating the status bar.
Creating custom panels.
Providing custom settings for the Settings panel.
.. and much more.

A list of all possible requests you can find on CKFinder.Application API page.

Please refer to Requests article for more details about requests and usage examples.

Events

Events are used in CKFinder to interact with the application when a specific situation occurs.

Thanks to the data passed to an event listener it is possible to do many things with CKFinder simply by listening for an event and changing the data. For example it is possible to modify toolbar buttons when listening for the toolbar:reset:Main:file event and changing evt.data.toolbar.

It is also possible to cancel an event.

All events are documented in the CKFinder.Application documentation. Among many features, events allow for:

Executing code when the application loads.
Executing code before or after a server-side command was requested, with the possibility to alter the data sent to the server.
Manipulating context menu items.
Manipulating toolbar buttons.
Specifying actions for buttons inside dialog windows.
Reacting when something was done with a file or a folder (e.g. a file was selected).
Executing code when pages are created, allowing you to add your own regions with views (render your own content).
Overwriting all templates used by CKFinder, making it possible to display any information in a different way.

Plugin Structure

All CKFinder plugins must have a pre-defined structure.

Each plugin inside the /plugins folder must be placed in a folder whose name is the same as the plugin name. The name of a JavaScript file with a plugin must follow the same rule.

Example: the MyPlugin plugin must be placed inside the plugins/MyPlugin/MyPlugin.js file.
If a plugin is intended to be loaded from a non-standard location, this rule does not apply but is considered a good practice. To load plugins from a custom location see config.plugins.
Plugins must be properly loaded by require.js AMD loader.
Other folders or files may exist inside the plugin folder , for instance a plugin might be divided into AMD modules.