Integration with CKEditor 4

The aim of this article is to show how to set up CKFinder with CKEditor 4 WYSIWYG editor.

CKFinder.setupCKEditor()

The simplest way to integrate CKFinder with CKEditor 4 is the CKFinder.setupCKEditor method. This method takes a CKEditor 4 instance which will be set up as the first argument (editor).

If no argument is passed or the editor argument is null, CKFinder will integrate with all CKEditor 4 instances.

Example 1

Integrate with a specific CKEditor 4 instance:

var editor = CKEDITOR.replace( 'editor1' );
CKFinder.setupCKEditor( editor );

Example 2

Integrate with all existing and future CKEditor 4 instances:

CKFinder.setupCKEditor();
CKEDITOR.replace( 'editor1' );

Passing Configuration Options to CKFinder

When using CKFinder inside CKEditor 4 it is still possible to pass required configuration options to the CKFinder instance. To do that you need to pass the configuration object as the second parameter to the CKFinder.setupCKEditor() method.

In the example below the default CKFinder skin is changed and a listener for the files:choose event is added. The listener is called when a file is chosen in CKFinder.

Example 3

Passing additional options with the CKFinder.setupCKEditor() method:

var editor = CKEDITOR.replace( 'editor1' );
CKFinder.setupCKEditor( editor, {
    skin: 'jquery-mobile',
    swatch: 'b',
    onInit: function( finder ) {
        finder.on( 'files:choose', function( evt ) {
            var file = evt.data.files.first();
            console.log( 'Selected: ' + file.get( 'name' ) );
        } );
    }
} );

Setting Custom Destination for Quick Uploads

The third argument of CKFinder.setupCKEditor() is an object that can be used to pass any parameters that will be appended to the URL used to upload files within CKEditor 4. You can use the type and currentFolder parameters to set the resource type and a folder where the uploaded files will be stored. It is also possible to pass some custom parameters.

Setting Target Resource Type

In order to specify the CKFinder resource type that the files should be uploaded to (via the Upload tab in CKEditor 4), pass the type parameter.

Example 4

CKFinder configured to upload files to the "Files" resource type:

var editor = CKEDITOR.replace( 'editor1' );
CKFinder.setupCKEditor( editor, null, { type: 'Files' } );

Note: The files will be uploaded to the root folder of the resource type.

Setting Target Folder

Apart from setting the target resource type for Quick Uploads, it is also possible to point to an exact path where the file should be uploaded using the currentFolder parameter.

Example 5

CKFinder configured to upload files to the archive subfolder of the "Files" resource type:

var editor = CKEDITOR.replace( 'editor1' );
CKFinder.setupCKEditor( editor, null, { type: 'Files', currentFolder: '/archive/' } );

Note: The specified folder must exist on the server.

Manual Integration

In order to manually configure CKEditor 4 to use CKFinder, you need to pass additional configuration settings to the CKEditor 4 instance.

Example 6

Enabling CKFinder in a CKEditor 4 instance using the same settings for all editor dialog windows:

[CKFinder 3 for PHP]

CKEDITOR.replace( 'editor1', {
    filebrowserBrowseUrl: '/ckfinder/ckfinder.html',
    filebrowserUploadUrl: '/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Files'
} );

[CKFinder 3 for ASP.NET]

CKEDITOR.replace( 'editor1', {
    filebrowserBrowseUrl: '/ckfinder/ckfinder.html',
    filebrowserUploadUrl: '/ckfinder/connector?command=QuickUpload&type=Files'
} );

Note: Remember to change the /ckfinder/ path in the URLs above if you installed CKFinder in a different location.

You can also set the global CKEditor 4 configuration using the CKEditor 4 config.js file.

filebrowserBrowseUrl vs filebrowserUploadUrl

The config.filebrowserUploadUrl configuration setting is responsible for enabling the "Upload" (1) tab ("Quick Uploads") in CKEditor 4 dialogs. The "Upload" tab offers the possibility to upload a file to the server without opening CKFinder in a separate window. It speeds up the editing process when the user does not want to select an existing image but simply needs to upload a new file.

The config.filebrowserBrowseUrl configuration setting is responsible for enabling the "Browse Server" (2) button in CKEditor dialogs. The "Browse Server" button opens CKFinder in a popup window. After the user selects a file in CKFinder it is passed back to the URL field of the previously opened dialog.

Adjusting the filebrowserBrowseUrl Setting

Setting Available Resource Types

It is possible to limit the available resource types ("root folders") in the CKFinder window by specifying the type attribute in the query string.

Example 7

Suppose that you only want to display the Files resource type when the user opens CKFinder. It can be easily achieved with the following code:

CKEDITOR.replace( 'editor1', {
    filebrowserBrowseUrl: '/ckfinder/ckfinder.html?resourceType=Files'
} );

Changing the Window Size

Although it is not recommended, it is possible to arbitrarily set the size of the CKFinder window using the following CKEditor configuration options:

• config.filebrowserWindowWidth
• config.filebrowserWindowHeight

Example 8

Setting the CKFinder window width and height using CKEditor 4 configuration options:

CKEDITOR.replace( 'editor1', {
    filebrowserBrowseUrl: '/ckfinder/ckfinder.html',
    filebrowserWindowWidth: '1000',
    filebrowserWindowHeight: '700'
} );

Adjusting the filebrowserUploadUrl Setting

Setting Target Resource Type for Quick Uploads

In order to specify the CKFinder resource type that the files should be uploaded to (via the Upload tab in CKEditor 4), pass the type attribute in the query string.

Example 9

CKFinder configured to upload files to the "Files" resource type:

[CKFinder 3 for PHP]

CKEDITOR.replace( 'editor1', {
    filebrowserUploadUrl: '/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Files'
} );

[CKFinder 3 for ASP.NET]

CKEDITOR.replace( 'editor1', {
    filebrowserUploadUrl: '/ckfinder/connector?command=QuickUpload&type=Files'
} );

Note: The files will be uploaded to the root folder of the resource type.

Setting Target Folder for Quick Uploads

Apart from setting the target resource type for Quick Uploads, it is also possible to point to an exact path where the file should be uploaded using the currentFolder attribute in the query string.

Example 10

CKFinder configured to upload files to the archive subfolder of the "Files" resource type:

[CKFinder 3 for PHP]

CKEDITOR.replace( 'editor1', {
    filebrowserUploadUrl:'/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Files&currentFolder=/archive/'
} );

[CKFinder 3 for ASP.NET]

CKEDITOR.replace( 'editor1', {
    filebrowserUploadUrl:'/ckfinder/connector?command=QuickUpload&type=Files&currentFolder=/archive/'
} );

Note: The specified folder must exist on the server.

Setting Different Configuration for CKEditor Dialog Windows

It is possible to provide different configuration for each CKEditor 4 dialog. The filebrowserBrowseUrl and filebrowserUploadUrl options set the CKEditor 4 configuration for all dialogs.

In order to specify a particular setting only for a selected dialog (e.g. the "Image" dialog), use the editor configuration options that include the dialog name.

Example 11

Setting specific configuration options for the "Image" and "Flash" dialogs:

[CKFinder 3 for PHP]

CKEDITOR.replace( 'editor1', {
    filebrowserBrowseUrl: '/ckfinder/ckfinder.html',
    filebrowserImageBrowseUrl: '/ckfinder/ckfinder.html?type=Images',
    filebrowserFlashBrowseUrl: '/ckfinder/ckfinder.html?type=Flash',
    filebrowserUploadUrl: '/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Files',
    filebrowserImageUploadUrl: '/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Images',
    filebrowserFlashUploadUrl: '/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Flash'
} );

[CKFinder 3 for ASP.NET]

CKEDITOR.replace( 'editor1', {
    filebrowserBrowseUrl: '/ckfinder/ckfinder.html',
    filebrowserImageBrowseUrl: '/ckfinder/ckfinder.html?type=Images',
    filebrowserFlashBrowseUrl: '/ckfinder/ckfinder.html?type=Flash',
    filebrowserUploadUrl: '/ckfinder/connector?command=QuickUpload&type=Files',
    filebrowserImageUploadUrl: '/ckfinder/connector?command=QuickUpload&type=Images',
    filebrowserFlashUploadUrl: '/ckfinder/connector?command=QuickUpload&type=Flash'
} );

Note: Resource type names in CKFinder are in plural form, hence the name of the resource type for the "Image" dialog window is Images.

How Does It Work?

Although rarely used, it is possible to specify settings for any dialog window by following the naming convention: filebrowser<dialog_name>BrowseUrl and filebrowser<dialog_name>UploadUrl, where <dialog_name> is the name of a dialog specified in the dialog definition, with the first letter uppercased. Unless you created your own CKEditor 4 plugin that provides a dialog window and a URL field, you can skip this paragraph.

In the "Full" CKEditor 4 installation package the dialogs with file browser support are:

• Link,
• Image,
• Flash.

The file browser can also be integrated with the optional Enhanced Image plugin dialog.