Real-time Collaboration

Release 3.0.0+

Enables multiple users to edit the same document simultaneously.

Sub-pages

Supported Browsers

  • Microsoft Edge (latest)
  • Google Chrome (latest)
  • Apple Safari (latest)
  • Other browsers may work but not all features are guaranteed.
  • Internet Explorer is not supported.

Setup

<script src="url of collaboration.min.js"></script>

<!-- CSS needed if you use the default user-info UI or the update-history dialog -->
<link rel="stylesheet" href="url of collaboration.min.css">

Configuration

WebSocket URL (required)

Without wsUrl the plugin doesn't initialize.

'collaboration.config': {
  'wsUrl': 'ws://websocket_url:1234'
}

Document ID (optional)

'collaboration.config': {
  'docId': 'documentId'
}

User Name, Cursor Color, User Data (optional)

If not specified, a random name (10 adjectives × 10 animals) and a random color (from 10 defaults) are used.

'collaboration.config': {
  'userName':  'SynapEditor',
  'userColor': '#39B6B8',
  'userData': {
    'userId':    'userId',     // your DB user id
    'connected': Date.now()    // arbitrary data
  }
}

User Profile Image (optional)

Release 3.2.2507+

'collaboration.config': {
  'userName':  'Synap',
  'userColor': '#39B6B8',
  'userData': {
    'profileImage': '/img/path.png'
  }
}

Default Name / Color Pool (optional)

When userName / userColor aren't set, picks randomly from these arrays.

'collaboration.config': {
  'defaultNames':  ['Puppy', 'Cat', 'Sparrow'],
  'defaultColors': ['#CDB4DB', '#F5CAC3', '#87BBA2']
}

Start / End Collaboration

Plugin APIs to start (init(), changeDocument(docId)) or end (destroy()) collaboration. See Plugin API.

Start via init()

Uses docId from config. If docId is empty, init does nothing.

// synapeditor.config.js
var synapEditorConfig = {
  // ...
  'collaboration.config': {
    'wsUrl': 'ws://websocket_url:1234',
    'docId': 'documentId'
  }
};

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

Start via changeDocument(docId)

Use without setting docId in config.

editor.plugins.collaboration.changeDocument('documentId');

End via destroy()

editor.plugins.collaboration.destroy();

Active Users UI

Built-in UI

Adds a toolbar button showing currently connected users. Click a user to jump to their caret position.

'editor.toolbar': [
  /* ... */ 'collaborator' /* ... */
]

Custom UI

See Custom User Info UI Guide.

Update History

Shows up to 100 recent edit events during a collaboration session, allowing restore. History resets when no one is connected.

'editor.toolbar': [
  /* ... */ 'updateHistory' /* ... */
]

In this section