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

Public
Inherited
Mixed
Protected
Private
Deprecated

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.
_adapter : Object

protected

Instance of the adapter.
_threadToController : Map.<CommentThread, CommentThreadController>

protected

Each thread attached as an annotation to the target element has a CommentThreadController that creates CommentThreadView and binds it with a CommentThread.

This map keeps connection between both of them.
_viewToController : Map.<CommentThreadView, CommentThreadController>

protected

Annotations plugin uses only a CommentThreadView and knows nothing about CommentThreadController.

This map helps to get a controller when only the view is known in some part of code.

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
- addCommentThread
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
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 read-only mode).

Fires
- addCommentThread
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
_addComment( data = { data.threadId, data.commentId, data.content, data.authorId, [data.createdAt], [data.attributes], [data.isFromAdapter] } )

protected
Parameters

data : Object

Data object.

Properties

data.threadId : String

Id of thread to which the comment will be added.

data.commentId : String

Comment id.

data.content : String

Comment content.

data.authorId : String

Author id.

[ data.createdAt ] : Date

Creation date. If not set, current date (new Date()) will be used.

[ data.attributes ] : Object

Custom comment attributes. See also setAttribute and removeAttribute.

[ data.isFromAdapter ] : Boolean

Defaults to false

Related:
- CommentThread#addComment
_attachCommentThread( data = { data.threadId, data.target } )

protected
Creates a CommentThreadController to create and bind CommentThreadView with CommentThread.
Created view is added to Annotations plugin and is will be displayed by one of the Annotations UI.

Parameters

data : Object

Properties

data.threadId : String

data.target : Object

Related:
- CommentThread#attachTo
_detachCommentThread( threadId )

protected

Hides comment thread instead of permanently remove.

Annotation with comment thread is removed, but CommentThread stays in the repository.

Parameters

threadId : String
_removeComment( data = { data.threadId, data.commentId, [data.isFromAdapter] } )

protected
Parameters

data : Object

Data object.

Properties

data.threadId : String

CommentThread id.

data.commentId : String

Comment id.

[ data.isFromAdapter ] : Boolean

Defaults to false

Related:
- Comment#remove
_removeCommentThread( threadId, isFromAdapter )

protected
Parameters

threadId : String

isFromAdapter : Boolean

Related:
- CommentThread#remove
_updateComment( data = { data.threadId, data.commentId, [data.content], [data.createdAt], [data.attributes], [data.isFromAdapter] } )

protected
Parameters

data : Object

Data object.

Properties

data.threadId : String

CommentThread id.

data.commentId : String

Comment id.

[ data.content ] : String

Comment content.

[ data.createdAt ] : Date

Creation date.

[ data.attributes ] : Object

Custom comment attributes. See also setAttribute and removeAttribute.

[ data.isFromAdapter ] : Boolean

Defaults to false

Related:
- Comment#update

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).

CommentsRepository (comments/comments)

Filtering

Properties

activeCommentThread : CommentThread | nullmodule:comments/comments/commentsrepository~CommentsRepository#activeCommentThread

adapter : CommentsAdaptermodule:comments/comments/commentsrepository~CommentsRepository#adapter

_adapter : Objectmodule:comments/comments/commentsrepository~CommentsRepository#_adapter

_threadToController : Map.<CommentThread, CommentThreadController>module:comments/comments/commentsrepository~CommentsRepository#_threadToController

_viewToController : Map.<CommentThreadView, CommentThreadController>module:comments/comments/commentsrepository~CommentsRepository#_viewToController

Methods

constructor()module:comments/comments/commentsrepository~CommentsRepository#constructor

addCommentThread( commentThreadData, [ data.channelId ], data.threadId, [ data.comments ], [ data.target ], [ data.isFromAdapter ] ) → CommentThreadmodule:comments/comments/commentsrepository~CommentsRepository#addCommentThread

Parameters

Returns

Fires

fetchCommentThread( data = { data.channelId, data.threadId } ) → Promise.<CommentThread>module:comments/comments/commentsrepository~CommentsRepository#fetchCommentThread

Parameters

Returns

getCommentThread( threadId ) → CommentThreadmodule:comments/comments/commentsrepository~CommentsRepository#getCommentThread

Parameters

Returns

getCommentThreads( [ options ] = { [options.channelId], [options.skipNotAttached], [options.skipEmpty], [options.toJSON] } ) → Array.<(CommentThread | Object)>module:comments/comments/commentsrepository~CommentsRepository#getCommentThreads

Parameters

Returns

hasCommentThread( threadId ) → Booleanmodule:comments/comments/commentsrepository~CommentsRepository#hasCommentThread

Parameters

Returns

openNewCommentThread( commentThreadData = { [commentThreadData.channelId], [commentThreadData.threadId], commentThreadData.target } ) → CommentThread | nullmodule:comments/comments/commentsrepository~CommentsRepository#openNewCommentThread

Parameters

Returns

Fires

setActiveCommentThread( threadId )module:comments/comments/commentsrepository~CommentsRepository#setActiveCommentThread

Parameters

switchReadOnly( value, [ channelId ] )module:comments/comments/commentsrepository~CommentsRepository#switchReadOnly

Parameters

_addComment( data = { data.threadId, data.commentId, data.content, data.authorId, [data.createdAt], [data.attributes], [data.isFromAdapter] } )module:comments/comments/commentsrepository~CommentsRepository#_addComment

Parameters

Related:

_attachCommentThread( data = { data.threadId, data.target } )module:comments/comments/commentsrepository~CommentsRepository#_attachCommentThread

Parameters

Related:

_detachCommentThread( threadId )module:comments/comments/commentsrepository~CommentsRepository#_detachCommentThread

Parameters

_removeComment( data = { data.threadId, data.commentId, [data.isFromAdapter] } )module:comments/comments/commentsrepository~CommentsRepository#_removeComment

Parameters

Related:

_removeCommentThread( threadId, isFromAdapter )module:comments/comments/commentsrepository~CommentsRepository#_removeCommentThread

Parameters

Related:

_updateComment( data = { data.threadId, data.commentId, [data.content], [data.createdAt], [data.attributes], [data.isFromAdapter] } )module:comments/comments/commentsrepository~CommentsRepository#_updateComment

Parameters

Related:

Events

addComment( eventInfo, data = { data.channelId, data.threadId, data.commentId, data.authorId, data.content, data.createdAt, data.isFromAdapter } )module:comments/comments/commentsrepository~CommentsRepository#event:addComment

Parameters

addCommentThread( eventInfo, data = { data.channelId, data.threadId, data.comments, [data.target], data.isFromAdapter } )module:comments/comments/commentsrepository~CommentsRepository#event:addCommentThread

Parameters

change:activeCommentThread( eventInfo, name, value, oldValue )module:comments/comments/commentsrepository~CommentsRepository#event:change:activeCommentThread

Parameters

removeComment( eventInfo, data = { data.channelId, data.threadId, data.commentId, data.isFromAdapter } )module:comments/comments/commentsrepository~CommentsRepository#event:removeComment

Parameters

removeCommentThread( eventInfo, data = { data.channelId, data.threadId, data.isFromAdapter } )module:comments/comments/commentsrepository~CommentsRepository#event:removeCommentThread

Parameters

updateComment( eventInfo, data = { data.channelId, data.threadId, data.commentId, data.content, [data.createdAt], data.isFromAdapter } )module:comments/comments/commentsrepository~CommentsRepository#event:updateComment

Parameters

`activeCommentThread : CommentThread | null`

`adapter : CommentsAdapter`

`_adapter : Object`

`_threadToController : Map.<CommentThread, CommentThreadController>`

`_viewToController : Map.<CommentThreadView, CommentThreadController>`

`constructor()`

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

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

`getCommentThread( threadId ) → CommentThread`

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

`hasCommentThread( threadId ) → Boolean`

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

`setActiveCommentThread( threadId )`

`switchReadOnly( value, [ channelId ] )`

`_addComment( data = { data.threadId, data.commentId, data.content, data.authorId, [data.createdAt], [data.attributes], [data.isFromAdapter] } )`

`_attachCommentThread( data = { data.threadId, data.target } )`

`_detachCommentThread( threadId )`

`_removeComment( data = { data.threadId, data.commentId, [data.isFromAdapter] } )`

`_removeCommentThread( threadId, isFromAdapter )`

`_updateComment( data = { data.threadId, data.commentId, [data.content], [data.createdAt], [data.attributes], [data.isFromAdapter] } )`

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

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

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

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

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

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