CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

CommentsRepository (comments/comments)

@ckeditor/ckeditor5-comments/src/comments/commentsrepository

class

Stores the list of CommentThread and provides event-driven API for managing them. It is also responsible for using the comments adapter to communicate with the data source.

CommentsRepository is a context plugin. It can be added to a context or to an editor. Add it to the context configuration if you use Context in your integration.

The event-driven API makes it possible to attach a listener to each action that changes comment data. Using different event priorities allows to attach an action before the main action ('low' priority) or after the main action ('high' priority). It works very similar to decorate.

Sample usage:

// Get the comments repository:
const commentsRepository = editor.plugins.get( 'CommentsRepository' );

// Create a new, empty comment thread on a DOM form field element:
commentsRepository.openNewCommentThread( { channelId, target: formFieldElement } );

// Get all comment threads:
commentsRepository.getCommentThreads();

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

For more information about the comments adapter see CommentsAdapter.

Filtering

Properties

  • activeCommentThread : CommentThread | null

    readonly observable

    The currently active comment thread. An annotation with this thread will be marked as active.

  • adapter : CommentsAdapter

    An adapter object that should communicate with the data source to fetch or save the comments data.

Methods

  • constructor()

  • addCommentThread( commentThreadData, [ data.channelId ], data.threadId, [ data.comments ], [ data.target ], [ data.isFromAdapter ] ) → CommentThread

    Adds a new comment thread.

    When a target is provided, the comment annotation will be attached to this target.

    Use this method to load the comments data during the editor initialization if you do not use the adapter integration.

    Note: This method fires the event-addCommentThread event and the default behavior is added as a 'normal' priority listener. It makes it possible to cancel the method or call some custom code before or after the default behavior is executed.

    Note: The comments adapter will send the data only if commentThreadData.comments is not empty and commentThreadData.isFromAdapter is set to false.

    See also CommentsRepository#openNewCommentThread().

    An example of loading a comment thread on editor initialization:

    commentsRepository.addCommentThread( {
    threadId: 'thread-id',
    channelId: 'channel-id',
    comments: [
        {
            commentId: 'comment-1',      // String
            authorId: 'author-id',       // String
            content: 'First comment',    // String
            createdAt: new Date( ... )   // Date instance
        },
        // ...
    ],
    target: () => ...,
    // Added during initialization, so do not call the adapter:
    isFromAdapter: true
} );

    Parameters

    commentThreadData : Object

    The data of the comment thread to add.

    [ data.channelId ] : String

    The ID of a document or context to which the comment thread is added.

    data.threadId : String

    The ID of the added comment thread.

    [ data.comments ] : Array.<Object>

    Comments in the comment thread. See the example above.

    Defaults to []

    [ data.target ] : HTMLElement | Rect | function

    The target that the comment balloon should be attached to. If a function is passed, it should return a DOM element or Rect.

    [ data.isFromAdapter ] : Boolean

    A flag describing whether the added data comes from an adapter (true) or is a new data (false). If set to true, the comment data will be added only in the editor and will not be sent to the adapter.

    Defaults to false

    Returns

    CommentThread

    The added comment thread.

    Fires

  • createCommentThreadController( commentThreadModel, commentThreadView )

    Create an instance of the CommentThreadController class.

    Parameters

    commentThreadModel : CommentThread

    Comment thread model.

    commentThreadView : BaseCommentThreadView

    Comment thread view.

  • fetchCommentThread( data = { data.channelId, data.threadId } ) → Promise.<CommentThread>

    Gets the comment thread data using the adapter and adds the thread to the editor.

    When the comment thread is already present in the repository, then the adapter will not be used but the result will be asynchronous as well.

    Parameters

    data : Object
    Properties
    data.channelId : String
    data.threadId : String

    Returns

    Promise.<CommentThread>

  • getCommentThread( threadId ) → CommentThread

    Returns comment thread of given id.

    Parameters

    threadId : String

    Returns

    CommentThread

  • getCommentThreads( [ options ] = { [options.channelId], [options.skipNotAttached], [options.skipEmpty], [options.toJSON] } ) → Array.<(CommentThread | Object)>

    Returns a list of comment threads added to the repository.

    You can provide a set of filtering options to narrow down the results set.

    Parameters

    [ options ] : Object
    Properties
    [ options.channelId ] : String

    Return only comment threads added to a given channel.

    [ options.skipNotAttached ] : Boolean

    Skip removed comment threads.

    Defaults to false

    [ options.skipEmpty ] : Boolean

    Skip empty comment threads.

    Defaults to false

    [ options.toJSON ] : Boolean

    Return the data in JSON format.

    Defaults to false

    Returns

    Array.<(CommentThread | Object)>

  • hasCommentThread( threadId ) → Boolean

    Checks if a comment thread with a given ID is added to the repository.

    Parameters

    threadId : String

    Returns

    Boolean

  • isReadOnly( channelId ) → Boolean

    Returns true if a given channel is set to read-only mode, returns false otherwise.

    Parameters

    channelId : String

    Returns

    Boolean

  • openNewCommentThread( commentThreadData = { [commentThreadData.channelId], [commentThreadData.threadId], commentThreadData.target } ) → CommentThread | null

    Creates a new, empty comment thread.

    Displays a new comment annotation attached to the target and focuses the comment editor. When the comment data is submitted, the comment thread is added to the editor and sent to the adapter.

    Use this method to start a new comment thread after a user performed an action (clicked a button, etc.).

    Parameters

    commentThreadData : Object
    Properties
    [ commentThreadData.channelId ] : String

    The ID of a document or context to which the comment is added.

    [ commentThreadData.threadId ] : String

    The ID of the comment thread. Random id will be generated if it is not set. All thread IDs should be unique.

    commentThreadData.target : HTMLElement | Rect | function

    The target that the comment balloon should be attached to. If a function is passed, it should return a DOM element or Rect.

    Returns

    CommentThread | null

    The created comment thread or null if there was a problem creating the thread (for example, if the comments repository was in the read-only mode).

    Fires

  • setActiveCommentThread( threadId )

    Marks a comment thread with the given ID as active. When threadId is null, the currently active comment thread will be deactivated.

    Parameters

    threadId : String | null

  • switchReadOnly( value, [ channelId ] )

    Changes the read-only state for comment threads.

    When the value is true then all comment threads will be switched to read-only, when the value is false then all comment threads will be switched to editing mode.

    Optionally new state can be applied to a comment threads limited to a given channel.

    Parameters

    value : Boolean
    [ channelId ] : String

Events

  • addComment( eventInfo, data = { data.channelId, data.threadId, data.commentId, data.authorId, data.content, data.createdAt, data.isFromAdapter } )

    Fired whenever a comment is added.

    The event name includes channelId so it is possible to listen only on changes happening in the specified channel.

    It is also possible to listen to events from the given thread ID by appending :[threadId] part to the event name

    const channelId = 'foo';
const threadId = '1234';

commentsRepository.on( `addComment:${ channelId }:${ threadId }`, ( evt, data ) => {
	console.log( evt, data );
} );

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    data : Object
    Properties
    data.channelId : String

    The ID of a document or context that the comment thread is added to.

    data.threadId : String

    The ID of the comment thread that the comment is added to.

    data.commentId : String

    The comment ID.

    data.authorId : String

    The comment author ID.

    data.content : String

    The comment content.

    data.createdAt : Date

    The comment creation date.

    data.isFromAdapter : Boolean

    A flag describing whether the comment was added on a remote client (true) or a local one (false).

  • addCommentThread( eventInfo, data = { data.channelId, data.threadId, data.comments, [data.target], data.isFromAdapter } )

    Fired whenever a comment thread is added to the comments repository.

    The event name includes channelId so it is possible to listen only on changes happening in the specified channel.

    	const channelId = 'foo';

commentsRepository.on( `addCommentThread:${ channelId }`, ( evt, data ) => {
		console.log( evt, data );
	} );

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    data : Object
    Properties
    data.channelId : String

    The ID of a document or context that the comment thread is added to.

    data.threadId : String

    The ID of the added comment thread.

    data.comments : Array.<Object>

    Comments in the comment thread.

    [ data.target ] : HTMLElement | Rect | function

    The target that the comment balloon should be attached to.

    data.isFromAdapter : Boolean

    A flag describing whether the comment thread was added on a remote client (true) or a local one (false).

  • change:activeCommentThread( eventInfo, name, value, oldValue )

    Fired when the activeCommentThread property changed value.

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    name : String

    Name of the changed property (activeCommentThread).

    value : CommentThread | null

    New value of the activeCommentThread property with given key or null, if operation should remove property.

    oldValue : CommentThread | null

    Old value of the activeCommentThread property with given key or null, if property was not set before.

  • removeComment( eventInfo, data = { data.channelId, data.threadId, data.commentId, data.isFromAdapter } )

    Fired whenever a comment is removed.

    The event name includes channelId so it is possible to listen only to changes happening in the specified channel.

    It is also possible to listen to events from the given thread ID by appending :[threadId] part to the event name

    const channelId = 'foo';
	const threadId = '1234';

	commentsRepository.on( `removeComment:${ channelId }:${ threadId }`, ( evt, data ) => {
		console.log( evt, data );
	} );

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    data : Object
    Properties
    data.channelId : String

    The ID of a document or context that the comment is removed from.

    data.threadId : String

    The ID of the comment thread that the comment is removed from.

    data.commentId : String

    The comment ID.

    data.isFromAdapter : Boolean

    A flag describing whether the comment was removed on a remote client (true) or a local one (false).

  • removeCommentThread( eventInfo, data = { data.channelId, data.threadId, data.isFromAdapter } )

    Fired whenever a comment thread is removed from the comments repository.

    The event name includes channelId so it is possible to listen only on changes happening in the specified channel.

    const channelId = 'foo';

commentsRepository.on( `removeCommentThread:${ channelId }`, ( evt, data ) => {
	console.log( evt, data );
} );

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    data : Object
    Properties
    data.channelId : String

    The ID of a document or context that the comment thread was removed from.

    data.threadId : String

    The ID of the comment thread to remove.

    data.isFromAdapter : Boolean

    A flag describing whether the comment thread was removed on a remote client (true) or a local one (false).

  • updateComment( eventInfo, data = { data.channelId, data.threadId, data.commentId, data.content, [data.createdAt], data.isFromAdapter } )

    Fired whenever a comment is updated.

    The event name includes channelId so it is possible to listen only to changes happening in the specified channel.

    It is also possible to listen to events from the given thread ID by appending :[threadId] part to the event name

    const channelId = 'foo';
const threadId = '1234';

commentsRepository.on( `updateComment:${ channelId }:${ threadId }`, ( evt, data ) => {
	console.log( evt, data );
} );

    Parameters

    eventInfo : EventInfo

    An object containing information about the fired event.

    data : Object
    Properties
    data.channelId : String

    The ID of a document or context where the comment was updated.

    data.threadId : String

    The ID of the comment thread where the comment was updated.

    data.commentId : String

    The comment ID.

    data.content : String

    The comment content.

    [ data.createdAt ] : Date

    The comment creation date.

    data.isFromAdapter : Boolean

    A flag describing whether the comment was updated on a remote client (true) or a local one (false).