Real-time collaborative editing

The RealTimeCollaborativeEditing plugin is the base of real-time 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 in real time and automatically solves all conflicts.

Collaborative selection design in CKEditor 5 WYSIWYG editor.

# Installation

Since collaboration features are not included in any default build, to use real-time collaborative editing you need to have a custom build which will include the RealTimeCollaborativeEditing plugin. You can use one created in the quick start guide or learn more about installing plugins and prepare your custom build.

When your build with real-time collaboration feature is ready, you can update the sample and add CKEditor Cloud Services configuration to it:

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

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

    <script src="../build/ckeditor.js"></script>
    <script>
        ClassicEditor.create( document.querySelector( '#editor' ), {
            toolbar: [ 'bold', 'italic', 'imageUpload' ],
            plugins: [ 'Essentials', 'Paragraph', 'Bold', 'Italic', 'EasyImage', 'RealTimeCollaborativeEditing' ],
            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'
            }
        } );
    </script>
</html>

If you do not have your CKEditor Cloud Services URLs yet, read more about them in the CKEditor Cloud Services Collaboration - Quick Start guide.

# 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 a basic understanding of all configuration options you pass to the editor configuration, except the documentID property.

The documentID 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 rich-text 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 content from CKEditor Could Services. Their local content does not matter as long as there is already an existing 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( 'RealTimeCollaborationClient' ).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 in real-time collaboration guide to learn more.