Increasing suggestions granularity

To maintain a low number of suggestions in the document, in some cases, the track changes feature automatically joins suggestions added by the same user. This happens when, for example, two insertion suggestions are made next to each other, or two formatting suggestions are made on the same text. This leads to a less cluttered UI, and as a result generally provides a better user experience.

However, in some specific cases, you may require to have more control over how and when suggestions are joined, and you might want to prevent this automatic mechanism. For this, you can use config.trackChanges.mergeNestedSuggestions configuration option and the tracking sessions mechanism.

# Auto-merging nested suggestions

By default, suggestions on an object (e.g. image, table) will be automatically merged with suggestions inside the object (e.g. a change in image caption, or a table cell). For example, creating a table and writing some text inside the table will result in one suggestion.

This behavior can be changed by setting the config.trackChanges.mergeNestedSuggestions configuration option to false. In the scenario above, there would be two separate suggestions: one for the inserted table and one for the inserted text.

{
    trackChanges: {
        mergeNestedSuggestions: false
    }
    // Other configuration
}

# Tracking sessions

To stop track changes from automatically joining suggestions made by the same user, start a new tracking session. Suggestions created in the new tracking session will not be joined with suggestions created in any of the previous tracking session.

From the technical point of view, after starting a new tracking session, newly created suggestions will have a unique trackingSessionId attribute. This will prevent them from being joined to already existing suggestions.

If you are using a non-real-time integration, make sure that you correctly save and load suggestion attributes together with the rest of the suggestion data.

# Starting a new tracking session

To start a new tracking session, call the TrackChangesEditing#startTrackingSession() method. From now on, all newly created suggestions will have a unique trackingSessionId attribute set. That ID value is returned by the method.

editor.plugins.get( 'TrackChangesEditing' ).startTrackingSession();

# Resuming previous session

You can also resume one of the previous tracking sessions by calling TrackChangesEditing#startTrackingSession() and passing a previously set trackingSessionId as the id parameter.

editor.plugins.get( 'TrackChangesEditing' ).startTrackingSession( 'somePreviousId' );

To “resume” tracking session for suggestions that were added before introducing TrackChangesEditing#startTrackingSession() you may pass null as the id parameter. It will also stop adding the trackingSessionId attribute to new suggestions.

editor.plugins.get( 'TrackChangesEditing' ).startTrackingSession( null );

# Demo

1. Add some text with track changes enabled. You may add more text next to created suggestions to see how the suggestions are automatically expanded.
2. Press the “Start new tracking session” button above the editor, and continue typing after one of the previously created suggestions.
3. See how new suggestion is created instead of expanding the existing suggestion.

# Starting a new session on editor initialization

One of the primary use cases is to start a new tracking session whenever the user opens the editor and/or after some time has passed.

Below you will find an example where a new tracking session is started whenever editor is created.

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // ... Editor configuration ...
    } )
    .then( editor => {
        // You can store the id if you need it later to resume previous tracking session.
        const trackingSessionId = editor.plugins.get( 'TrackChangesEditing' ).startTrackingSession();
    } )
    .catch( /* ... */ );