Contribute to this guideReport an issue

guideCKFinder file manager integration

This feature allows you to insert images as well as links to files into the rich-text editor content. It is a bridge between the CKEditor 5 WYSIWYG editor and the CKFinder file manager and uploader.

Check out the comprehensive Image upload overview to learn about other ways to upload images into CKEditor 5.

This feature can be used in the rich-text editor in two different ways:

  • As a server-side connector only (demo). In this scenario, images which are dropped or pasted into the editor are uploaded to the CKFinder server-side connector running on your server.

  • As a server and client-side file manager integration (demo). Images dropped and pasted directly into the editor are uploaded to the server (just like in the first option).

    But there are more cool features available, for instance:

    • uploading using the full user interface,
    • uploading multiple files at once,
    • browsing previously uploaded images,
    • editing images (cropping, resizing, etc.),
    • organizing or deleting images.

    Check out the CKFinder file manager website to learn more about the features you can use in your project.

This feature is enabled by default in all builds.

# Demo

# Image upload only

This demo shows the integration where the file manager’s server connector handles the image upload only:

  • Paste the image directly into the rich-text editor content and it will be automatically uploaded using the server-side connector.
  • Use the “Insert image” button in the toolbar to insert an image.
Use the toolbar button to insert an image.

# Full integration

This demo shows the full integration with the CKFinder file uploader:

  • Paste the image directly into the rich-text editor content and it will be automatically uploaded using the server-side connector.
  • Use the “Insert image or file” button in the toolbar to open the CKFinder file manager and insert an image or a link to any other file.
Use the toolbar button to open the CKFinder file manager. Use the file manager's interface to insert an image or a link to a file.

# Configuration

The feature is configurable by using the config.ckfinder object.

# Configuring the image upload only

This feature can upload images automatically to the server (e.g. when the image is dropped into the content) thanks to the CKFinder upload adapter. All it requires is the correct config.ckfinder.uploadUrl path.

Assuming that the CKFinder PHP server-side connector is installed (available) under https://example.com/ckfinder/, use the following quick upload command URL to enable the image upload:

import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ CKFinder, ... ],

        // Enable the "Insert image" button in the toolbar.
        toolbar: [ 'imageUpload', ... ],

        ckfinder: {
            // Upload the images to the server using the CKFinder QuickUpload command.
            uploadUrl: 'https://example.com/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Images&responseType=json'
        }
    } )
    .then( ... )
    .catch( ... );

See the demo of the image upload only.

# Configuring the full integration

To use both the image upload functionality and the file manager user interface in your application, you must first load the CKFinder JavaScript library and then enable CKFinder integration in your rich-text editor instance.

The easiest way to load the CKFinder library is to include the <script> tag loading the ckfinder.js file first:

<script src="https://example.com/ckfinder/ckfinder.js"></script>

Then:

  • Make sure that the CKFinder plugin for CKEditor 5 is enabled. See the Installation section.
  • In order to enable the automatic file upload to the server when an image is pasted or dropped into the editor content, remember to set the correct config.ckfinder.uploadUrl path.
  • In order to display the toolbar button that opens the CKFinder file manager UI allowing the users to choose the files on the server, make sure that 'ckfinder' is present in your config.toolbar.
  • Additionally, you can use config.ckfinder.options to define CKFinder’s options. For example:
    • You can define options.resourceType to tell CKFinder the specified resource type can be browsed when the user clicks the button.
    • You can define options.language to set the UI language of CKFinder. By default it will be set to the UI language of the editor.
import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ CKFinder, ... ],

        // Enable the CKFinder button in the toolbar.
        toolbar: [ 'ckfinder', ... ]

        ckfinder: {
            // Upload the images to the server using the CKFinder QuickUpload command.
            uploadUrl: 'https://example.com/ckfinder/core/connector/php/connector.php?command=QuickUpload&type=Images&responseType=json',

            // Define the CKFinder configuration (if necessary).
            options: {
                resourceType: 'Images'
            }
        }
    } )
    .then( ... )
    .catch( ... );

See the demo of the full integration.

# Configuring the opener

You can change the way CKFinder opens using the config.ckfinder.openerMethod option.

By default, the file manager opens as a modal. To open it in a new “pop-up” window, set the configuration value to popup:

import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ CKFinder, ... ],
        toolbar: [ 'ckfinder', ... ]
        ckfinder: {
            // Open the file manager in the pop-up window.
            openerMethod: 'popup'
        }
    } )
    .then( ... )
    .catch( ... );

# Installation

This feature is enabled by default in all builds. The installation instructions are for developers interested in building their own, custom WYSIWYG editor.

To add this feature to your editor, install the @ckeditor/ckeditor5-ckfinder package:

npm install --save @ckeditor/ckeditor5-ckfinder

Then add CKFinder to your plugin list and configure the feature (when necessary). For instance:

import CKFinder from '@ckeditor/ckeditor5-ckfinder/src/ckfinder';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ CKFinder, ... ],
        toolbar: [ 'ckfinder', 'imageUpload' ... ], // Depending on your preference.
        ckfinder: {
            // Feature configuration.
        }
    } )
    .then( ... )
    .catch( ... );

# Common API

The CKFinder plugin registers:

  • The 'ckfinder' UI button component.

  • The 'ckfinder' command implemented by the CKFinderCommand.

    You can open CKFinder by executing the following code:

    editor.execute( 'ckfinder' );
    

Additionally, in the “image upload only” integration, you can use the following button and command registered by the ImageUpload plugin:

  • The 'imageUpload' UI button component.
  • The 'imageUpload' command implemented by the ImageUploadCommand.

# Contribute

The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-ckfinder.