CKBox file manager

CKBox is a dedicated asset manager supporting file and image upload. The CKBox feature lets you easily upload various files and insert images and links to other files into your content. It also offers image conversion and optimization capabilities and provides a responsive images mechanism for CKEditor 5.

# How CKBox enhances CKEditor 5

As a full-fledged file manager, CKBox also replaces the basic CKEditor 5 image upload feature. It provides image and file upload and management capabilities:

• Enables drag & drop uploads of images and other files.
• Transforms the Image toolbar button, allowing the user to quickly upload and insert an image without opening the CKBox UI.
• Adds a separate dedicated toolbar button to open the CKBox UI to manage and reuse uploaded files.
• Provides basic editing capabilities, like crop, resize, rotate, and flip right from the image contextual toolbar for images served by CKBox.
• Supports workspaces that allow separating assets for different users.

With CKBox you no longer need to write server-side code to upload and scale images or manage uploaded files.

To find out more about CKBox, the brand-new file manager and image editor, visit the CKBox website and read the dedicated CKBox documentation page.

# Demo

To upload a file using CKBox, use the open file manager toolbar button . You can choose more than one file at a time. Use the edit image button from either the main toolbar or the image contextual toolbar to edit the selected image.

Note that the image toolbar button will now also upload images right into the CKBox file manager and you can drag and drop them, too. You can then access the files from the management panel.

Image files are inserted into the content as images that you can drag around and resize. Non-embeddable files (like PDF files) are inserted as links.

You can also upload images by dragging them into your content. After you drag an image into the editor, it gets uploaded into the CKBox cloud storage and inserted into the content.

# Installation

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/latest/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:

• The ImageBlock feature
• The ImageInline feature
• The Image feature (a glue plugin that loads both the ImageBlock and ImageInline features)

These plugins are, by default, loaded with predefined builds, such as ClassicEditor. If you do not have any of them in your editor, install one and add it to your plugin list.

Please also remember, that the CKBox plugin requires the following dependency plugins to work properly: PictureEditing, ImageUpload, and CloudServices. Except for ImageUpload which is, likewise, available in predefined builds, these need to be added manually.

You must include the CKBoxImageEdit plugin if you want to use CKBox image editing capabilities from within CKEditor 5.

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

import { ImageUpload, PictureEditing } from '@ckeditor/ckeditor5-image';
import { CloudServices } from '@ckeditor/ckeditor5-cloud-services';
import { CKBox, CKBoxImageEdit } from "@ckeditor/ckeditor5-ckbox";

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

Further in the document, the dependency plugins will be omitted in code listings for clarity.

# Adding the image editing button to the image toolbar

To invoke the CKBox image editor straight from the image contextual toolbar (available at right-click in an image), it needs to be added to the toolbar configuration.

The snippet below shows an example image contextual toolbar configuration.

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        image: {
            toolbar: [ 'toggleImageCaption', 'imageTextAlternative', 'ckboxImageEdit' ]
        }
    } )

# Configuration

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

# Before you start

After you purchase a license, log into the CKEditor Ecosystem customer dashboard to create access credentials, as explained in the CKBox configuration guide.

# Defining upload categories

By default, the 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 changes.

import { CKBox } from '@ckeditor/ckeditor5-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( /* ... */ );

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.

# Defining default upload workspace

The CKBox workspaces provide a convenient solution for achieving data isolation and user separation within CKBox. With workspaces, you can easily create separate storage and data spaces, giving you precise control over assigning specific users, user groups, or tenants to each workspace.

If the user is assigned to more than one workspace, by default all the files uploaded directly from CKEditor are located in the first workspace in the list of workspaces allowed in the user’s JWT token. This corresponds to uploads through drag and drop into the editor area, pasting images from the clipboard, or images uploaded using the Image feature. If you would like to define a specific workspace for files uploaded this way, you can define its ID in the defaultUploadWorkspaceId option. After that, all the files uploaded directly from CKEditor will be placed in the specified workspace.

import { CKBox } from '@ckeditor/ckeditor5-ckbox';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ CKBox, /* ... */ ],
        toolbar: [ 'ckbox', /* ... */ ],
        ckbox: {
            tokenUrl: 'https://your.token.url',
            // Sample workspace referenced by its ID.
            defaultUploadWorkspaceId: [ 'pHUSQFj_QIvc' ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

You can obtain the list of available workspaces using the Workspaces REST API.

# 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';

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';

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/latest/ckbox.js"></script>
<script src="https://cdn.ckbox.io/CKBox/1.2.1/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';

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

# Configuring the API service

If you host the cloud service in your environment, you should configure the base URL of the API service via the config.ckbox.serviceOrigin option:

import { CKBox } from '@ckeditor/ckeditor5-ckbox';

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

# Editing external images

If you want to allow CKBox to edit external images, not hosted by the file manager (for example, pasted via URL) you need to whitelist the URLs of the images. You can do this using the config.ckbox.allowExternalImagesEditing option:

import { CKBox } from '@ckeditor/ckeditor5-ckbox';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ CKBox, /* ... */ ],
        toolbar: [ 'ckbox', /* ... */ ],
        ckbox: {
            allowExternalImagesEditing: [ 'origin', /^cksource.com/ ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

The image is editable if this option is:

• a regular expression and it matches the image URL, or
• a custom function that returns true for the image URL, or
• origin literal and the image URL is from the same origin, or
• an array of the above and the image URL matches one of the array elements.

# Common API

The CKBox plugin registers:

• The 'ckbox' UI button component for CKBox asset manager.
• The 'ckbox' command implemented by the CKBoxCommand.

You can open CKBox by executing the following code:

editor.execute( 'ckbox' );

If you want to use the CKBox editing capabilities straight from the editor, the plugin will also register the following:

• The 'ckboxImageEdit' UI button component for the CKBox image editor.
• The 'ckboxImageEdit' command implemented by the CKBoxImageEdit.

# 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 at https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-ckbox.