CKEditor Ecosystem Documentation
Search
Home/CKBox/Getting started

guideCKEditor integration

CKBox feature is enabled by default in all the predefined CKEditor builds. In this guide, we will focus on the simplest integration scenario, where both CKEditor and CKBox are added to the web page using links from the CDN.

First, add the two following scripts to the HTML of your webpage:

<script src="https://cdn.ckeditor.com/ckeditor5/36.0.0/classic/ckeditor.js"></script>
<script src="https://cdn.ckbox.io/ckbox/1.5.1/ckbox.js"></script>

For the purpose of this example, we will use the classic editor build, but there is many more builds to choose from! You can learn more about running CKEditor 5 from the CDN from a dedicated guide in the CKEditor 5 documentation.

To enable CKBox in your CKEditor instance, add all the required configuration options to the object under the ckbox key. In the simplest scenario, CKBox requires only the tokenUrl option.

# Quick example

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script src="https://cdn.ckeditor.com/ckeditor5/36.0.0/classic/ckeditor.js"></script>
        <script src="https://cdn.ckbox.io/ckbox/1.5.1/ckbox.js"></script>
    </head>
    <body>
        <div id="editor"></div>
        <script>
            ClassicEditor
                .create( document.querySelector( '#editor' ), {
                    ckbox: {
                        tokenUrl: 'https://your.token.url',
                    },
                    toolbar: [
                        'ckbox', 'imageUpload', '|', 'heading', '|', 'undo', 'redo', '|', 'bold', 'italic', '|',
                        'blockQuote', 'indent', 'link', '|', 'bulletedList', 'numberedList'
                    ],
                } )
                .catch( error => {
                    console.error( error );
                } );
        </script>
    </body>
</html>

The demo sample below presents the result of this integration. Try pasting images from the clipboard directly into the editing area as well as dropping images — the files will be saved on the fly by CKBox.

You can use the toolbar button to open the CKBox dialog window. There you can manage your files or choose an asset that should be added to the edited content. The image embedded in the editor this way will produce a highly optimized <picture> tag. If the image has a description set in its properties in CKBox, the description will be automatically used as an alt attribute of the image embedded in the editor.

# Configuration options

Using the ckbox attribute, you can pass any of the available configuration options to a CKBox instance.

As an example, let’s run both CKEditor 5 and CKBox in Spanish, and additionally let’s set the theme of CKBox to dark.

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script src="https://cdn.ckeditor.com/ckeditor5/36.0.0/classic/ckeditor.js"></script>
        <script src="https://cdn.ckeditor.com/ckeditor5/36.0.0/classic/translations/es.js"></script>
        <script src="https://cdn.ckbox.io/ckbox/1.5.1/ckbox.js"></script>
        <script src="https://cdn.ckbox.io/ckbox/1.5.1/translations/es.js"></script>
        <link rel="stylesheet" href="https://cdn.ckbox.io/ckbox/1.5.1/styles/themes/dark.css">
    </head>
    <body>
        <div id="editor"></div>
        <script>
            ClassicEditor
                .create( document.querySelector( '#editor' ), {
                    language: 'es',
                    ckbox: {
                        tokenUrl: 'https://your.token.url',
                        theme: 'dark'
                    },
                    toolbar: [
                        'ckbox', 'imageUpload', '|', 'heading', '|', 'undo', 'redo', '|', 'bold', 'italic', '|',
                        'blockQuote', 'indent', 'link', '|', 'bulletedList', 'numberedList'
                    ],
                } )
                .catch( error => {
                    console.error( error );
                } );
        </script>
    </body>
</html>

As you can see in the example above, the language option for CKBox was omitted. This was intentional because by default, the language of CKBox will match the language of CKEditor 5, which has been already set to Spanish. Setting language again in ckbox.language would be superfluous in this case.

Below you can see a live example of the configuration presented above.

# Plugin-specific options

CKEditor 5 plugin for CKBox exposes two plugin-specific options. These options are used to configure the plugin and are not passed down to the CKBox instance.

# defaultUploadCategories

When uploading the asset to CKBox by dropping or pasting it into the editor area, the asset by default lands into the first category that allows the asset extension. There might be cases where you would like to have more control over this, e.g. when two or more categories are configured to allow for the same file extension (please refer to the Category management guide to read more about category configuration options in the administration panel). The defaultUploadCategories option allows to explicitly define categories that should be used to upload the particular extensions.

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        ckbox: {
            tokenUrl: 'https://your.token.url',
            defaultUploadCategories: {
                // Category referenced by name
                Files: ['pdf', 'txt', 'zip'],
                // Category referenced by ID
                'fdf2a647-b67f-4a6c-b692-5ba1dc1ed87b': ['jpg', 'png']
            }
        }
    } )
    .catch( error => {
        console.error( error );
    } );

As you can see in the example above, the category can be referenced either by its name or by ID. When referencing the category by its name, you will have to update this configuration if the category name is changed. Referencing the category by ID is a more bulletproof solution because the category ID always remains the same. The category ID can be found in the Asset categories section of the administration panel.

Administration panel - category ID.

Please note that extensions assigned to categories in defaultUploadCategories must be in sync with the extensions allowed for categories in the Asset categories section of the administration panel. If the extension is not allowed in the category configuration in the administration panel, the file will not be uploaded.

# ignoreDataId

When assets are inserted into the editor content, the CKBox plugin for CKEditor will by default add a data-ckbox-resource-id. The purpose of this tag is to bind the content to the CKBox asset and allow for basic asset usage tracking (i.e. checking which CKBox assets are used in your content).

For example:

<a href="..." data-ckbox-resource-id="hAza1FIb2YIV">link</a>

If you want to disable this feature, please set the ignoreDataId option to true.

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        ckbox: {
            tokenUrl: 'https://your.token.url',
            ignoreDataId: true
        }
    } )
    .catch( error => {
        console.error( error );
    } );

# Advanced integration

To read about more advanced integration scenarios, please refer to the CKBox file manager article in the CKEditor 5 documentation.