Contribute to this guide

guideCKBox file manager

This CKBox integration feature allows you to effortlessly and intuitively insert images as well as links to other files into the rich-text editor content. CKBox is a file manager and a file uploader that acts as a convenient interface for the cloud storage service. The CKBox feature provides a simple integration with this service for the CKEditor 5 WYSIWYG editor. To find out more about CKBox, the brand-new file manager, visit the CKBox website.

CKBox is a commercial solution. Please contact us if you would like to purchase a license. Let us know if you have any feedback or questions!

You can also sign up for the CKEditor Premium Features 30-day free trial.

This feature is enabled by default in all predefined builds for convenience, but the editor will still work properly without activating it.

# Demo

Try CKBox in action. Use the Open file manager toolbar button Open file manager to invoke the CKBox dialog window. After the dialog is opened, find an interesting image and click on the Choose button. The selected image should be inserted into the editor content. You can choose more than one file at once. Play around with these, changing the alignment and size.

Non-embeddable files (e.g. PDF files) will be inserted into editor content as links. To test it, open the CKBox dialog again and choose any PDF file. It should be inserted as a link in the editor content. After clicking this link, it is automatically downloaded.

The CKBox feature also supports uploading images. Drag any image into the editor content and it will be uploaded into the CKBox cloud storage. The uploaded file is then automatically inserted in the editor content. If you want to upload a non-image file type (such as a PDF or a text file) to the cloud storage, just open the CKBox dialog and use the Upload button.

Diesel locos are really useful!

A diesel locomotive is one that uses a diesel engine as the prime source of power to move and pull the cars.

Diesel locomotives are very popular today and can be seen working on all continents (with the exception of Antarctica maybe, where the railway network is rather scarce). Being powerful and not requiring additional technical infrastructure like their younger siblings — the electric locomotives — diesel engines are perfect for most types of tasks.

Diesel engines can pull passenger trains, boxcars with goods, tank cars, platform wagons with wood logs... Should the conditions be tough and the load be too heavy for a single diesel locomotive, that can be put together in a pair of engines. And sometimes you can even see three of four of them if the job is exceptionally demanding.

Most national and private railway companies nowadays own or lease a multitude of diesel engines, ranging from small, nimble ones used for maneuvering on the station to the bulky, large ones for the cross-continental trail.

Diesel engines also come in all shapes and all colors, making up a happy useful bunch.

This demo only presents a limited set of features. Visit the full-featured editor example to see more in action.

# Installation

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

To use this feature in your application, you must first load the CKBox library and then enable CKBox integration in your rich-text editor instance.

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

<script src="https://cdn.ckbox.io/CKBox/1.1.0/ckbox.js"></script>

Then, install the @ckeditor/ckeditor5-ckbox package:

npm install --save @ckeditor/ckeditor5-ckbox

The CKBox feature requires one of the following plugins to be loaded to work correctly:

If you do not have any of them in your editor, install one and add it to your plugin list.

Finally, add CKBox to your plugin list and configure the feature as needed. An example configuration may look like this:

import CKBox from '@ckeditor/ckeditor5-ckbox/src/ckbox';

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

# Configuration

The feature can be configured via the config.ckbox object.

# Defining upload categories

By default, CKBox feature maps the uploaded image type to the category configured on the cloud service. You can override this behavior and provide your own mappings via the config.ckbox.defaultUploadCategories configuration option. It is an object, where the keys define categories and their values are the types of images that will be uploaded to these categories. The categories might be referenced either by their name or by their ID. Referencing by ID is future-proof, because it will not require configuration changes when a category name is changed.

import CKBox from '@ckeditor/ckeditor5-ckbox/src/ckbox';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ CKBox, ... ],
        toolbar: [ 'ckbox', ... ],
        ckbox: {
            defaultUploadCategories: {
                Bitmaps: [ 'bmp' ],
                Pictures: [ 'jpg', 'jpeg' ],
                Scans: [ 'png', 'tiff' ],
                // The category below is referenced by its ID.
                'fdf2a647-b67f-4a6c-b692-5ba1dc1ed87b': [ 'gif' ]
            }
        }
    } )
    .then( ... )
    .catch( ... );

Please keep in mind that if you define your own upload category mappings for a particular image type, only your first found category will be taken into account while finding the appropriate category for the uploaded image. Category mappings configured on the server will not be searched in that case. The image will not be uploaded (and hence inserted into the editor) in the following cases:

  • If you have defined your own category mapping in defaultUploadCategories for the uploaded image type:
    • the category does not exist on the server,
    • the category exists on the server, but the server configuration does not allow the uploaded image type.
  • If you have not defined your own category mapping in defaultUploadCategories for the uploaded image type:
    • there is no category mapping for the uploaded image type on the server.

# Adding the ID for inserted assets

After choosing an asset from the CKBox dialog, it is inserted into the editor content with a unique data-ckbox-resource-id attribute. If you want to disable it and do not want to add this attribute, set the config.ckbox.ignoreDataId option to true:

import CKBox from '@ckeditor/ckeditor5-ckbox/src/ckbox';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ CKBox, ... ],
        toolbar: [ 'ckbox', ... ],
        ckbox: {
            ignoreDataId: true
        }
    } )
    .then( ... )
    .catch( ... );

# Changing the language

By default, the CKBox dialog takes the current language from the editor. If you want to use a different language, you can set the language code in the config.ckbox.language option:

import CKBox from '@ckeditor/ckeditor5-ckbox/src/ckbox';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ CKBox, ... ],
        toolbar: [ 'ckbox', ... ],
        ckbox: {
            language: 'es'
        }
    } )
    .then( ... )
    .catch( ... );

Also, make sure to include the translation file after loading the CKBox library:

<script src="https://cdn.ckbox.io/CKBox/1.1.0/ckbox.js"></script>
<script src="https://cdn.ckbox.io/CKBox/1.1.0/translations/es.js"></script>

# Providing the token URL

The CKBox feature requires the token endpoint URL configured in the config.ckbox.tokenUrl key. If not explicitly provided, the token URL from config.cloudServices.tokenUrl is used instead. If both are provided, the token URL defined in config.ckbox.tokenUrl takes precedence over the config.cloudServices.tokenUrl.

import CKBox from '@ckeditor/ckeditor5-ckbox/src/ckbox';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ CKBox, ... ],
        toolbar: [ 'ckbox', ... ],
        ckbox: {
            tokenUrl: 'https://example.com/cs-token-endpoint'
        }
    } )
    .then( ... )
    .catch( ... );

# Configuring the API service and assets origin

If the cloud service is hosted in your own environment you should configure the base URL of the API service via the config.ckbox.serviceOrigin, and config.ckbox.assetsOrigin options:

import CKBox from '@ckeditor/ckeditor5-ckbox/src/ckbox';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ CKBox, ... ],
        toolbar: [ 'ckbox', ... ],
        ckbox: {
            serviceOrigin: 'https://example.com/',
            assetsOrigin: 'https://cloud.example.com/',
        }
    } )
    .then( ... )
    .catch( ... );

# Common API

The CKBox plugin registers:

  • The 'ckbox' UI button component.

  • The 'ckbox' command implemented by the CKBoxCommand.

    You can open CKBox by executing the following code:

    editor.execute( 'ckbox' );
    

We recommend using the official CKEditor 5 inspector for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.

# What’s next?

Be sure to check out the comprehensive Image upload overview guide to learn more about different ways of uploading images in CKEditor 5.

See the image feature guide to find out more about handling images in CKEditor 5 in general.

# Contribute

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