[Collaboration] Plugin API

Table of Contents

• EVENT_TYPE
• on(eventType, listener)
  • parameters:
• off(eventType, listener)
  • parameters:
• setUserName(name)
  • parameters:
• setUserColor(color)
  • parameters:
• setUserData(data)
  • parameters:
• getClientId()
  • Return:
• init()
• changeDocument(docId)
  • parameters:
• destroy()
• setInit(fn)
  • parameters:
• getHistory()
  • Return:
• updateHistoryOriginal(modelJSON)
  • parameters:
• applyChanges()

EVENT_TYPE

Event types that can be used in the Collaboration plugin.

You can register or remove listeners for events using the on() and off() methods.

ON_SYNC

• Occurs when the real-time collaboration session is connected.
• Values passed as listener parameters:

ON_SYNC event

{
    setForceUpdate: (update: boolean) => void
}

• setForceUpdate(update): When true, forces the collaboration model to be overwritten with the editor's current model.

example

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;
var EVENT_TYPE = collaboration.EVENT_TYPE;

collaboration.on(EVENT_TYPE.ON_SYNC, function (event) {
    event.setForceUpdate(true);
});

USER_CHANGED

• Occurs when the number of connected users changes.
• Values passed as listener parameters:

USER_CHANGED users

List of currently connected users.

{
    id:       number,    // client ID
    name:     string,
    color:    string,
    data:     Object,
    position: Position,
    modified: number,    // last update timestamp
    self:     boolean
}

example

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;
var EVENT_TYPE = collaboration.EVENT_TYPE;

collaboration.on(EVENT_TYPE.USER_CHANGED, function (users, added, removed) {
    console.log(users, added, removed);
});

USER_INFO_CHANGED

• Occurs when a connected user's name, color, or cursor position changes. Also fires when the user count changes.
• Values passed as listener parameters:

example

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;
var EVENT_TYPE = collaboration.EVENT_TYPE;

collaboration.on(EVENT_TYPE.USER_INFO_CHANGED, function (users) {
    console.log(users);
});

DOCUMENT_UPDATED

Release 3.0.2404 and above.

• Occurs when the document is changed.
• Values passed as listener parameters:

DOCUMENT_UPDATED user

The user who made the change.

{
    id:    number,
    name:  string,
    color: string,
    self:  boolean
}

example

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;
var EVENT_TYPE = collaboration.EVENT_TYPE;

collaboration.on(EVENT_TYPE.DOCUMENT_UPDATED, function (user) {
    console.log(user);
});

on(eventType, listener)

Registers a listener for events occurring in the Collaboration plugin.

parameters:

Example:

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;
var EVENT_TYPE = collaboration.EVENT_TYPE;
var eventListener = function () {};

collaboration.on(EVENT_TYPE.USER_CHANGED, eventListener);

off(eventType, listener)

Removes a listener for events occurring in the Collaboration plugin.

parameters:

Example:

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;
var EVENT_TYPE = collaboration.EVENT_TYPE;
var eventListener = function () {};

collaboration.off(EVENT_TYPE.USER_CHANGED, eventListener);

setUserName(name)

Sets the current user's name.

parameters:

Example:

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;

collaboration.setUserName('user-name');

setUserColor(color)

Sets the current user's color.

parameters:

Example:

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;

collaboration.setUserColor('#39b6b8');

setUserData(data)

Stores arbitrary information about the current user.

parameters:

Example:

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;

collaboration.setUserData({ userId: 'userId', connected: Date.now() });

getClientId()

Returns the current user's client ID.

Return:

Example:

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;

var id = collaboration.getClientId();

init()

Initializes collaboration.

If docId is set in the plugin configuration, the session starts with that document. Without docId, this method does nothing.

Example:

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;

collaboration.init();

changeDocument(docId)

Switches to a different document.

parameters:

Example:

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;

collaboration.changeDocument('newDocumentId');

destroy()

Ends the current user's collaboration session.

Example:

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;

collaboration.destroy();

setInit(fn)

Sets a callback function to run when the session is initialized.

parameters:

Example:

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;

collaboration.setInit(function () {
    console.log('Collaboration connected');
});

getHistory()

Returns the edit history.

Return:

Up to Release 3.0.x:

{
    original: string,       // JSON string of the editor model when history started
    versions: [
        {
            data:     string,   // JSON string of the editor model after the change
            modified: number,   // client timestamp
            user:     { id: number, name: string }
        }
        // ... up to 100 entries
    ]
}

Release 3.1.0 and above:

[
    {
        modified:     number,
        rootModified: boolean,    // whether the document's root (body) was modified
        snapshot:     Uint8Array, // model snapshot after the change
        user:         { id: number, name: string, color: string }
    }
    // ...
]

Example:

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;

var history = collaboration.getHistory();

updateHistoryOriginal(modelJSON)

Deprecated in Release 3.1.0 and above.

Updates the "original" model of the edit history. Calling without modelJSON uses the editor's current model. versions is reset.

parameters:

Example:

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;

collaboration.updateHistoryOriginal();

applyChanges()

Pushes editor-side changes that bypassed the action system into the collaboration model, so other clients see them.

Scenarios where this is needed:

• After editor.insertHTML(...)
• After editing via APIModel

Example:

var editor = new SynapEditor(id, synapEditorConfig);
var collaboration = editor.plugins.collaboration;

editor.insertHTML('SynapEditor');                                  // local only
collaboration.applyChanges();                                       // sync

editor.getAPIModelById('myParagraph').replace('SynapSoft');         // local only
collaboration.applyChanges();                                       // sync