Track changes API

# TrackChanges

Below is the public track changes API provided by the TrackChanges plugin.

/**
 * An adapter object that should communicate with the data source
 * to fetch or save the suggestions data.
 */
adapter

/**
 * Adds suggestion data.
 *
 * Use this method to load the suggestion data during the editor initialization
 * if you do not use the adapter integration.
 *
 * @param {Object} suggestionData The data of a suggestion to add.
 */
addSuggestion( suggestionData ) {}

/**
 * Returns the suggestion data for a given ID.
 *
 * @param {String} id The suggestion ID.
 * @returns {Object}
 */
getSuggestion( id ) {}

/**
 * Iterates through the suggestion data for all the suggestions that are
 * present in the editor content.
 *
 * @returns {Array.<Object>}
 */
getSuggestions() {}

To use this API, you need to get the track changes plugin:

// Get the track changes plugin:
const trackChangesPlugin = editor.plugins.get( 'TrackChanges' );

// Add a suggestion:
trackChangesPlugin.addSuggestion( { ... } );

// Get all suggestions:
trackChangesPlugin.getSuggestions();

// Set the adapter:
trackChangesPlugin.adapter = {
    ...
};

# Suggestion data object

Below is the suggestion data structure expected by TrackChanges#addSuggestion() and returned by TrackChanges#getSuggestion() and TrackChanges#getSuggestions().

{
    id: 'suggestion-1',         // String
    type: 'insertion',          // String
    authorId: 'user-1',         // String
    createdAt: new Date( ... ), // Date
    hasComments: false          // Boolean
    data: { ... }               // Object|null
}

# Track changes adapter

The track changes adapter is an object that communicates asynchronously with the data source to fetch or save the suggestion data. It is used internally by the track changes feature whenever a suggestion is loaded, created or deleted.

The adapter is optional. You might need to provide it if you are using the track changes feature without real-time collaboration.

To set the adapter, overwrite the TrackChanges#adapter property.

/**
 * Called each time the suggestion data is needed.
 *
 * The method should return a promise that resolves with the suggestion data object.
 *
 * @param {String} id The ID of the suggestion to get.
 * @returns {Promise}
 */
getSuggestion( id ) {}

/**
 * Called each time a new suggestion is created.
 *
 * The method should save the suggestion data in the database
 * and return a promise that should be resolved when the save is
 * completed.
 *
 * If the promise resolves with an object with the `createdAt` property,
 * this suggestion property will be updated in the suggestion in the editor.
 * This lets you update the suggestion data with server-side information.
 *
 * The `suggestionData` object does not expect the `authorId` property.
 * For security reasons, the author of the suggestion should be set
 * on the server side.
 *
 * If `suggestionData.originalSuggestionId` is set, the new suggestion should
 * have the `authorId` property set to the same as the suggestion with
 * `originalSuggestionId`. This happens when one user breaks
 * another user's suggestion, creating a new suggestion as a result.
 *
 * In any other case, use the current (local) user to set `authorId`.
 *
 * The `suggestionData` object does not expect the `createdAt` property either.
 * You should use the server-side time generator to ensure that all users
 * see the same date.
 *
 * @param {Object} suggestionData
 * @param {String} suggestionData.id The suggestion ID.
 * @param {String} suggestionData.type The suggestion type. It may include a subtype; the
 * format is then <type>:<subtype>.
 * @param {Boolean} suggestionData.hasComments Always `false`, a new suggestion does not have comments.
 * @param {String} [suggestionData.originalSuggestionId] The ID of the suggestion from which
 * the `authorId` property should be taken.
 * @param {Object|null} [suggestionData.data] Additional suggestion data. Used by format suggestions.
 * @returns {Promise}
 */
addSuggestion( suggestionData ) {}

/**
 * Called each time the suggestion data has changed. The only data that
 * may change is information whether a suggestion has comments or not, and the suggestion state.
 * When the first comment is added to the suggestion, the only
 * comment is removed from the suggestion or the suggestion was accepted or rejected,
 * the `updateSuggestion()` method is called with proper data.
 *
 * For suggestions with `hasComments` set to `false`, the editor
 * will not try to fetch the comment thread through the comments adapter.
 *
 * The method should update the suggestion data in the database
 * and return a promise that should be resolved when the save is
 * completed.
 *
 * @param {String} id The suggestion ID.
 * @param {Object} suggestionData The suggestion data to update.
 * @param {Boolean} suggestionData.hasComments Defines if the suggestion has comments or not.
 * @param {'open'|'accepted'|'rejected'} suggestionData.state Sets the suggestion state.
 * @returns {Promise}
 */
updateSuggestion( id, suggestionData ) {}

# Commands

The track changes plugin adds a set of commands to the editor. These commands are executed when you turn on the track changes mode, accept a suggestion, etc. You do not need to care about the commands if you are integrating the track changes plugin together with the UI part. However, knowing about them might be useful if you are working on a custom UI.

The following commands are available:

• trackChanges – Toggles the track changes mode in the editor.
• acceptSuggestion – Accepts a suggestion with the specified ID.
• discardSuggestion – Discards a suggestion with the specified ID.
• acceptAllSuggestions – Accepts all suggestions.
• discardAllSuggestions – Discards all suggestions.
• acceptSelectedSuggestions – Accepts all suggestions in the current selection.
• discardSelectedSuggestions – Discards all suggestions in the current selection.

Examples:

editor.execute( 'trackChanges' );
editor.execute( 'acceptSuggestion', 'suggestion-1' );
editor.execute( 'discardSuggestion', 'suggestion-1' );
editor.execute( 'acceptAllSuggestions' );
editor.execute( 'discardAllSuggestions' );
editor.execute( 'acceptSelectedSuggestions' );
editor.execute( 'discardSelectedSuggestions' );

Note that there is no command to add a suggestion. This is because suggestions are added automatically when editing commands are executed while the editor is in track changes mode. For instance:

// Turn on the track changes mode:
editor.execute( 'trackChanges' );

// Insert some text. It will be automatically inserted as a suggestion:
editor.execute( 'input', { text: 'foo' } );