Collaborative editing

The CollaborativeEditing plugin is the base of collaboration in CKEditor 5. It allows for editing the same document by multiple users at the same time. It also shows the selection of other users and automatically solves all conflicts.

Collaborative selection design.

# Installation

The collaboration feature needs a cloud service to synchronize content between the clients, so first you need to sign up to the Collaboration service powered by CKEditor Cloud Services. Refer to Collaboration - Quick Start for more details.

Then, you need to create a custom build, because this plugin is not included in any of the offered official builds. The following instructions describe step-by-step what you need to do.

# Prepare a custom build

Collaborative editing is not included in any CKEditor 5 build. To enable it, you need to create a custom CKEditor 5 build that would include the collaboration feature. Please get familiar with CKEditor 5 Framework - Quick start as you will need to understand it in order to run collaboration examples.

Once you install packages needed to build CKEditor 5 and prepare the webpack configuration, you need to install all packages you want to use. In case of the sample below it is:

npm install --save \
    @ckeditor/ckeditor5-dev-utils \
    @ckeditor/ckeditor5-editor-classic \
    @ckeditor/ckeditor5-essentials \
    @ckeditor/ckeditor5-paragraph \
    @ckeditor/ckeditor5-basic-styles \
    @ckeditor/ckeditor5-theme-lark \
    @ckeditor/ckeditor5-easy-image \
    @ckeditor/ckeditor5-collaboration

Use this code to enable collaborative editing in classic editor:

// app.js

import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
import EasyImageUpload from '@ckeditor/ckeditor5-easy-image/src/easyimage';

import CollaborativeEditing from '@ckeditor/ckeditor5-collaboration/src/collaborativeediting';

ClassicEditor
    .create( document.querySelector( '.editor' ), {
        plugins: [ Essentials, Paragraph, Bold, Italic, CollaborativeEditing, EasyImageUpload ],
        cloudServices: {
            // PROVIDE CORRECT VALUES HERE:
            tokenUrl: 'https://example.com/cs-token-endpoint',
            uploadUrl: 'https://your-organization-id.cke-cs.com/easyimage/upload/',
            webSocketUrl: 'your-organization-id.cke-cs.com/ws/',
            documentId: 'collabEditing'
        },
        toolbar: [ 'bold', 'italic', 'imageUpload' ]
    } )
    .then( editor => {
        window.editor = editor;
    } )
    .catch( error => console.error( error ) );

As in any other custom build, you need to place your bundle in an HTML document:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>CKEditor 5 Collaboration – Hello World!</title>
    </head>

    <div class="editor">
        <p>Let's edit this together!</p>
    </div>

    <script src="dist/bundle.js"></script>
</html>

Voilà! All users who open this page should be able to collaborate, working on this document at the same time.

Although classic editor was used in the previous example, collaboration, like every other official CKEditor 5 plugin, will work with any editor creator.

You can now continue reading this tutorial to learn more about the integration, or jump directly to the Collaborative comments guide to enable adding comments to the document.

# Integration

When your collaborative document is up and running it is time to think about the integration with your application.

Do note that CKEditor Cloud Services does not save or load the document content. It is a medium to handle the collaboration process. Content management should be handled by the integrated application.

# Data initialization

At this point, you should have basic understanding of all configuration options you pass to the editor configuration, except the documentID property.

This is a very important property when you collaborate. It tells CKEditor Cloud Services which editor instances should collaborate. All editor instances created with the same document ID will collaborate. It means that each document needs a different document ID if you do not want to start collaboration between these documents. The ID is usually a primary key of the document in the database, but you are free to provide whatever identifier fits your scenario.

When the first user with a certain document ID opens the editor, their content is sent to CKEditor Could Services. In case of the example above it is:

<p>Let's edit this together!</p>

Then, when the next user connects to the same document, they get the context from CKEditor Could Services. Their local content does not matter as long as there is already a created document with connected users. The document is removed from CKEditor Could Services a while after the last user disconnects.

This is the reason why you should not use the setData() methods after the editor is initialized using the collaboration plugin. The content of the editor needs to be defined before the editor initialization, so the collaboration plugin can decide which data should be used.

# Saving data

The document is temporarily stored in the cloud by CKEditor Cloud Services only when there are connected users. It means that when the last user disconnects, the content should be saved in the database on your server. However, there might be a conflict when two collaborating users are saving the same document and the older document overwrites the new one.

To prevent race conditions, the cloudDocumentVersion variable is provided:

editor.plugins.get( 'CollaborationClient' ).cloudDocumentVersion

It is a number that defines which client has a newer version of the document. This number should be stored in the database together with the content. When any client wants to save the content, document versions should be compared. The document should only be saved when the version is higher. Otherwise, it means that this is an older version of the document and there is already a newer version saved.

The collaborative editing feature not only synchronizes the document content between all participants, but it also shows each user the selection of all other users in real time. It works out of the box and does not require any additional configuration. This is the only part of the collaborative editing plugin that provides a UI. See the Users guide to learn more.