Integration with CKEditor 4
Contents
The aim of this article is to show how to set up CKFinder with CKEditor 4 WYSIWYG editor.
Note: This guide is only valid for CKEditor 4.
If you want to integrate CKFinder with CKEditor 5, refer to the Integration with CKEditor 5 article.
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 some examples URLs to the server connector are used. Such examples are additionally labeled with the name of the CKFinder distribution to which the code sample applies to.
The filebrowser*BrowseUrl
paths must point to the location of ckfinder.html
, which in case of installation from NuGet packages in the ASP.NET connector is by default located in /ckfinder/CKFinderScripts/ckfinder.html
.
The filebrowser*UploadUrl
paths in CKFinder 2.x and CKFinder 3.x are different.
The filebrowserUploadUrl
and filebrowserImageUploadUrl
paths point to the connector's route. These paths are virtual and do not exist on the disk.
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:
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¤tFolder=/archive/'
} );
[CKFinder 3 for ASP.NET]
CKEDITOR.replace( 'editor1', {
filebrowserUploadUrl:'/ckfinder/connector?command=QuickUpload&type=Files¤tFolder=/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:
The file browser can also be integrated with the optional Enhanced Image plugin dialog.