CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Interface

TrackChangesAdapter (track-changes)

@ckeditor/ckeditor5-track-changes/src/trackchanges

interface

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 features/collaboration/track-changes/track-changes-integration using the track changes feature without real-time collaboration.

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

Filtering

Methods

  • addSuggestion( suggestionData = { suggestionData.id, suggestionData.type, suggestionData.hasComments, [suggestionData.data], [suggestionData.attributes], [suggestionData.originalSuggestionId] } ) → Promise

    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 splits another user's suggestion, creating a new suggestion as a result. See Track changes integration guide.

    Note: Failure to properly handle this property will result in editor crash in some scenarios.

    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.

    It is recommended to stringify suggestionData.attributes value to JSON and save it as a string in your database, and then to parse the strings when loading suggestions.

    Parameters

    suggestionData : Object
    Properties
    suggestionData.id : String

    The suggestion ID.

    suggestionData.type : String

    The suggestion type. It may include a subtype - the format is then :.

    suggestionData.hasComments : Boolean

    Always false. A new suggestion does not have comments.

    [ suggestionData.data ] : Object | null

    Additional suggestion data. Used by format suggestions.

    [ suggestionData.attributes ] : Object

    Custom suggestion attributes.

    [ suggestionData.originalSuggestionId ] : String | null

    The ID of the suggestion from which the authorId property should be taken.

    Returns

    Promise

  • getSuggestion( id ) → Promise

    Called each time the suggestion data is needed.

    The method should return a promise that resolves with the suggestion data object.

    Parameters

    id : String

    The ID of the suggestion to get.

    Returns

    Promise

  • updateSuggestion( id, suggestionData = { [suggestionData.hasComments], [suggestionData.state], [suggestionData.attributes] } ) → Promise

    Called each time the suggestion properties change.

    The method should update the suggestion properties in the database and return a promise that should be resolved when the save is completed.

    Keep in mind that the data parameter only contains those properties of a suggestion which changed.

    Parameters

    id : String

    The suggestion ID.

    suggestionData : Object

    The suggestion data to update.

    Properties
    [ suggestionData.hasComments ] : Boolean

    Defines if the suggestion has comments or not.

    [ suggestionData.state ] : 'open' | 'accepted' | 'rejected'

    The suggestion state.

    [ suggestionData.attributes ] : Object

    Custom suggestion attributes.

    Returns

    Promise